From ed98ef612e8d3782cdfa7250a6916afb84d09776 Mon Sep 17 00:00:00 2001
From: Sergio Valor <jaildesigner@gmail.com>
Date: Tue, 19 May 2026 12:43:01 +0200
Subject: [PATCH] Fase 3: import del subsistema de audio desde AEEA
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reemplaza el audio antiguo de orni_attack (singleton con new/delete
raw, sin efectos, sin crossfade) por el subsistema moderno de AEEA
(unique_ptr, RAII, crossfade nativo, echo/reverb, pitch-shift,
callbacks de fin de pista, getMusicDurationMs para timelines
deterministas).

Eliminados:
- source/core/audio/audio_cache.{hpp,cpp} (1 cache por subsistema)
- source/core/audio/jail_audio.hpp viejo (motor inline globals)
- source/external/stb_vorbis.h (v1.20)

Añadidos (copiados de AEEA, traducidos comentarios al castellano):
- source/core/audio/audio.{hpp,cpp} — singleton con Audio::Config inyectada
- source/core/audio/audio_adapter.{hpp,cpp} — adapter para getMusic/getSound
- source/core/audio/audio_effects.{hpp,cpp} — Schroeder reverb + echo DSP
- source/core/audio/jail_audio.{hpp,cpp} — Ja::Engine class-based, streaming
- source/core/audio/sound_effects_config.{hpp,cpp} — presets YAML (opcional)
- source/external/stb_vorbis.c (v1.22) — OGG decoder, versión más reciente
- source/external/stb_vorbis_impl.cpp — TU aislada para evitar clang-tidy

Adaptaciones:
- audio_adapter.cpp implementado a medida para orni: usa
  Resource::Helper::loadFile (no Resource::Cache de AEEA que orni no
  tiene). Cache local con unique_ptr<Ja::Music> / unique_ptr<Ja::Sound>.
- Includes: utils/defaults.hpp -> core/defaults.hpp, utils/log.hpp
  reemplazado por iostream con std::cerr/std::cout.

API breaking changes (callsites migrados):
- Audio::init() -> Audio::init(Config); el Director construye la Config
  desde Defaults::Audio::* (ENABLED, VOLUME, MUSIC_*, SOUND_*).
- Audio::get()->getMusicState() -> Audio::getMusicState() (ahora static).
- AudioCache::getMusic/getSound -> AudioResource::getMusic/getSound.

Defaults::Audio consolidado: ahora aglutina las constantes que antes
estaban repartidas entre namespace Audio (VOLUME, ENABLED), namespace
Music (VOLUME, ENABLED), namespace Sound (VOLUME, ENABLED). Las pistas
y rutas de efectos siguen en Music::* / Sound::*. Añadidas FREQUENCY,
FORMAT, CHANNELS, CROSSFADE_MS, VOLUME_STEP para el motor.

Beneficios para fases siguientes:
- Crossfade en transiciones de escena (uso: playMusic(name, -1, 1500)).
- Pitch-shift para variaciones de SFX (Audio::playSound(name, group, 0.95)).
- Echo/reverb DSP via playSoundWithEcho/Reverb (sounds.yaml presets).
- Callbacks setOnMusicEnded para sincronizar eventos con el fin de pista.

Compila y enlaza. Pendiente: test runtime del usuario.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 source/core/audio/audio.cpp                   | 328 +++++---
 source/core/audio/audio.hpp                   | 222 ++++--
 source/core/audio/audio_adapter.cpp           |  99 +++
 source/core/audio/audio_adapter.hpp           |  19 +
 source/core/audio/audio_cache.cpp             | 142 ----
 source/core/audio/audio_cache.hpp             |  42 --
 source/core/audio/audio_effects.cpp           | 251 +++++++
 source/core/audio/audio_effects.hpp           |  38 +
 source/core/audio/jail_audio.cpp              | 645 ++++++++++++++++
 source/core/audio/jail_audio.hpp              | 708 ++++++------------
 source/core/audio/sound_effects_config.cpp    |  80 ++
 source/core/audio/sound_effects_config.hpp    |  36 +
 source/core/defaults.hpp                      |  19 +-
 source/core/system/director.cpp               |  26 +-
 .../external/{stb_vorbis.h => stb_vorbis.c}   | 117 +--
 source/external/stb_vorbis_impl.cpp           |  13 +
 source/game/options.cpp                       |  20 +-
 source/game/scenes/title_scene.cpp            |   2 +-
 source/game/stage_system/stage_manager.cpp    |   2 +-
 19 files changed, 1893 insertions(+), 916 deletions(-)
 create mode 100644 source/core/audio/audio_adapter.cpp
 create mode 100644 source/core/audio/audio_adapter.hpp
 delete mode 100644 source/core/audio/audio_cache.cpp
 delete mode 100644 source/core/audio/audio_cache.hpp
 create mode 100644 source/core/audio/audio_effects.cpp
 create mode 100644 source/core/audio/audio_effects.hpp
 create mode 100644 source/core/audio/jail_audio.cpp
 create mode 100644 source/core/audio/sound_effects_config.cpp
 create mode 100644 source/core/audio/sound_effects_config.hpp
 rename source/external/{stb_vorbis.h => stb_vorbis.c} (98%)
 create mode 100644 source/external/stb_vorbis_impl.cpp

diff --git a/source/core/audio/audio.cpp b/source/core/audio/audio.cpp
index 6adf336..8bb79d0 100644
--- a/source/core/audio/audio.cpp
+++ b/source/core/audio/audio.cpp
@@ -1,183 +1,291 @@
-#include "audio.hpp"
+#include "core/audio/audio.hpp"
 
-#include <SDL3/SDL.h>  // Para SDL_LogInfo, SDL_LogCategory, SDL_G...
+#include <SDL3/SDL.h>  // Para SDL_GetError, SDL_Init
 
 #include <algorithm>  // Para clamp
-#include <iostream>   // Para std::cout
+#include <cstdio>     // Para std::fprintf
 
-// Implementación de stb_vorbis (debe estar ANTES de incluir jail_audio.hpp)
-// clang-format off
-#undef STB_VORBIS_HEADER_ONLY
-#include "external/stb_vorbis.h"
-// clang-format on
+#include "core/audio/audio_adapter.hpp"         // Para AudioResource::getMusic/getSound
+#include "core/audio/jail_audio.hpp"            // Para Ja::* (motor jailgames)
+#include "core/audio/sound_effects_config.hpp"  // Para SoundEffectsConfig
+#include "core/defaults.hpp"                    // Para Defaults::Audio::FREQUENCY
 
-#include "core/audio/audio_cache.hpp"  // Para AudioCache
-#include "core/audio/jail_audio.hpp"   // Para JA_FadeOutMusic, JA_Init, JA_PauseM...
-#include "game/options.hpp"            // Para AudioOptions, audio, MusicOptions
+// Invariant compile-time: tots los valors d'Audio::Group han de cabre als slots
+// de volum per grup que manté l'engine. Si s'afegeix una nueva entrada a Group
+// y no s'incrementa Ja::MAX_GROUPS, este assert falla antes de compilar.
+static_assert(static_cast<int>(Audio::Group::INTERFACE) < Ja::MAX_GROUPS,
+    "Audio::Group té més entrades que slots té Ja::MAX_GROUPS");
 
 // Singleton
-Audio* Audio::instance = nullptr;
+std::unique_ptr<Audio> Audio::instance;
 
-// Inicializa la instancia única del singleton
-void Audio::init() { Audio::instance = new Audio(); }
+// Inicialitza la instància única del singleton con la configuración rebuda
+void Audio::init(const Config& config) { Audio::instance = std::unique_ptr<Audio>(new Audio(config)); }
 
-// Libera la instancia
-void Audio::destroy() { delete Audio::instance; }
+// Allibera la instància
+void Audio::destroy() { Audio::instance.reset(); }
 
-// Obtiene la instancia
-auto Audio::get() -> Audio* { return Audio::instance; }
+// Obté la instància
+auto Audio::get() -> Audio* { return Audio::instance.get(); }
 
 // Constructor
-Audio::Audio() { initSDLAudio(); }
+Audio::Audio(const Config& config)
+    : config_(config) { initSDLAudio(); }
 
-// Destructor
-Audio::~Audio() {
-    JA_Quit();
-}
+// Destructor: engine_ es std::unique_ptr, el seu dtor tanca el device SDL i
+// desregistra Ja::Engine::active_. Cap crida explícita necessària.
+Audio::~Audio() = default;
 
-// Método principal
+// Método principal: l'estat de la música el manté el motor (única font de
+// veritat), per tant no cal sin sincronització aquí.
 void Audio::update() {
-    JA_Update();
+    if (instance && instance->engine_) { instance->engine_->update(); }
 }
 
-// Reproduce la música
-void Audio::playMusic(const std::string& name, const int loop) {
-    bool new_loop = (loop != 0);
+// Reprodueix la música per nom (amb crossfade opcional)
+void Audio::playMusic(const std::string& name, const int loop, const int crossfade_ms) {
+    const bool NEW_LOOP = (loop != 0);
 
-    // Si ya está sonando exactamente la misma pista y mismo modo loop, no hacemos nada
-    if (music_.state == MusicState::PLAYING && music_.name == name && music_.loop == new_loop) {
+    // Si ya sona exactament la misma pista i mismo mode loop, no fem res
+    if (getMusicState() == MusicState::PLAYING && music_.name == name && music_.loop == NEW_LOOP) {
         return;
     }
 
-    // Intentar obtener recurso; si falla, no tocar estado
-    auto* resource = AudioCache::getMusic(name);
-    if (resource == nullptr) {
-        // manejo de error opcional
-        return;
-    }
+    if (!music_enabled_) { return; }
 
-    // Si hay algo reproduciéndose, detenerlo primero (si el backend lo requiere)
-    if (music_.state == MusicState::PLAYING) {
-        JA_StopMusic();  // sustituir por la función de stop real del API si tiene otro nombre
-    }
+    auto* resource = AudioResource::getMusic(name);
+    if (resource == nullptr) { return; }
 
-    // Llamada al motor para reproducir la nueva pista
-    JA_PlayMusic(resource, loop);
-
-    // Actualizar estado y metadatos después de start con éxito
+    playMusicInternal(resource, loop, crossfade_ms);
     music_.name = name;
-    music_.loop = new_loop;
-    music_.state = MusicState::PLAYING;
 }
 
-// Pausa la música
+// Reprodueix la música per punter (amb crossfade opcional)
+void Audio::playMusic(Ja::Music* music, const int loop, const int crossfade_ms) {
+    if (!music_enabled_ || music == nullptr) { return; }
+
+    playMusicInternal(music, loop, crossfade_ms);
+    // Si el Ja::Music es va crear con filename (loadMusic con 3 arguments), el
+    // recuperem porque getCurrentMusicName() no menteixi. Si no, music_.name
+    // queda buit — el contracte d'este overload no garanteix el nom.
+    music_.name = music->filename;
+}
+
+// Camí comú dels dos overloads: fa el dispatch crossfade vs stop+play i
+// actualitza el loop cachejat. Els callers s'encarreguen del gating
+// (music_enabled_, nullptr, same-track early return) y del nom. L'estat el
+// manté Ja (Ja::playMusic posa PLAYING al Ja::Music* corresponent).
+void Audio::playMusicInternal(Ja::Music* music, const int loop, const int crossfade_ms) {
+    const bool CURRENTLY_PLAYING = (getMusicState() == MusicState::PLAYING);
+    if (crossfade_ms > 0 && CURRENTLY_PLAYING) {
+        engine_->crossfadeMusic(music, crossfade_ms, loop);
+    } else {
+        if (CURRENTLY_PLAYING) {
+            engine_->stopMusic();
+        }
+        engine_->playMusic(music, loop);
+    }
+
+    music_.loop = (loop != 0);
+}
+
+// Pausa la música (l'estat el transiciona Engine::pauseMusic)
 void Audio::pauseMusic() {
-    if (music_enabled_ && music_.state == MusicState::PLAYING) {
-        JA_PauseMusic();
-        music_.state = MusicState::PAUSED;
+    if (music_enabled_ && getMusicState() == MusicState::PLAYING) {
+        engine_->pauseMusic();
     }
 }
 
-// Continua la música pausada
+// Continua la música pausada (l'estat el transiciona Engine::resumeMusic)
 void Audio::resumeMusic() {
-    if (music_enabled_ && music_.state == MusicState::PAUSED) {
-        JA_ResumeMusic();
-        music_.state = MusicState::PLAYING;
+    if (music_enabled_ && getMusicState() == MusicState::PAUSED) {
+        engine_->resumeMusic();
     }
 }
 
-// Detiene la música
+// Atura la música (l'estat el transiciona Engine::stopMusic)
 void Audio::stopMusic() {
     if (music_enabled_) {
-        JA_StopMusic();
-        music_.state = MusicState::STOPPED;
+        engine_->stopMusic();
     }
 }
 
-// Reproduce un sonido por nombre
-void Audio::playSound(const std::string& name, Group group) const {
+void Audio::setMusicSpeed(float ratio) {
+    if (music_enabled_) {
+        engine_->setMusicSpeed(ratio);
+    }
+}
+
+// Reprodueix un so per nom
+void Audio::playSound(const std::string& name, Group group) {
     if (sound_enabled_) {
-        JA_PlaySound(AudioCache::getSound(name), 0, static_cast<int>(group));
+        engine_->playSound(AudioResource::getSound(name), 0, static_cast<int>(group));
     }
 }
 
-// Reproduce un sonido por puntero directo
-void Audio::playSound(JA_Sound_t* sound, Group group) const {
+// Reprodueix un so per punter directe
+void Audio::playSound(Ja::Sound* sound, Group group) {
+    if (sound_enabled_ && sound != nullptr) {
+        engine_->playSound(sound, 0, static_cast<int>(group));
+    }
+}
+
+// Variant con velocitat (i to) escalats. Apliquem el ratio al canal
+// just retornat per `playSound`: así el `SDL_AudioStream` recent creat
+// processa tot el sample con el ratio des del primer pull del callback.
+// Si l'engine torna -1 (sense canal lliure) o el so no existeix, no fem
+// la crida al ratio — sin efectes col·laterals.
+void Audio::playSound(const std::string& name, Group group, float speed) {
+    if (!sound_enabled_) { return; }
+    auto* sound = AudioResource::getSound(name);
+    if (sound == nullptr) { return; }
+    const int CH = engine_->playSound(sound, 0, static_cast<int>(group));
+    if (CH >= 0 && speed != 1.0F) {
+        engine_->setChannelSpeed(CH, speed);
+    }
+}
+
+// Reprodueix un so processat per un eco definit a sounds.yaml. Si el preset no
+// existeix o l'engine retorna -1 (sin de canals d'efecte plé), cau a playSound
+// sec — l'usuari sent el so aún que la cua no s'apliqui.
+void Audio::playSoundWithEcho(const std::string& name, const std::string& preset_name, Group group) {
+    if (!sound_enabled_) { return; }
+    auto* sound = AudioResource::getSound(name);
+    if (sound == nullptr) { return; }
+
+    const auto* params = SoundEffectsConfig::get().findEcho(preset_name);
+    if (params == nullptr) {
+        std::fprintf(stderr, "Audio: preset d'eco '%s' desconegut — so '%s' es reprodueix sec\n", preset_name.c_str(), name.c_str());
+        engine_->playSound(sound, 0, static_cast<int>(group));
+        return;
+    }
+
+    if (engine_->playSoundWithEcho(sound, *params, static_cast<int>(group)) < 0) {
+        engine_->playSound(sound, 0, static_cast<int>(group));
+    }
+}
+
+// Reprodueix un so processat per un reverb definit a sounds.yaml. Mateix
+// fallback que playSoundWithEcho.
+void Audio::playSoundWithReverb(const std::string& name, const std::string& preset_name, Group group) {
+    if (!sound_enabled_) { return; }
+    auto* sound = AudioResource::getSound(name);
+    if (sound == nullptr) { return; }
+
+    const auto* params = SoundEffectsConfig::get().findReverb(preset_name);
+    if (params == nullptr) {
+        std::fprintf(stderr, "Audio: preset de reverb '%s' desconegut — so '%s' es reprodueix sec\n", preset_name.c_str(), name.c_str());
+        engine_->playSound(sound, 0, static_cast<int>(group));
+        return;
+    }
+
+    if (engine_->playSoundWithReverb(sound, *params, static_cast<int>(group)) < 0) {
+        engine_->playSound(sound, 0, static_cast<int>(group));
+    }
+}
+
+// Atura tots los sons
+void Audio::stopAllSounds() {
     if (sound_enabled_) {
-        JA_PlaySound(sound, 0, static_cast<int>(group));
+        engine_->stopChannel(-1);
     }
 }
 
-// Detiene todos los sonidos
-void Audio::stopAllSounds() const {
-    if (sound_enabled_) {
-        JA_StopChannel(-1);
+// Fa una fosa de sortida de la música
+void Audio::fadeOutMusic(int milliseconds) {
+    if (music_enabled_ && getMusicState() == MusicState::PLAYING) {
+        engine_->fadeOutMusic(milliseconds);
     }
 }
 
-// Realiza un fundido de salida de la música
-void Audio::fadeOutMusic(int milliseconds) const {
-    if (music_enabled_ && getRealMusicState() == MusicState::PLAYING) {
-        JA_FadeOutMusic(milliseconds);
-    }
+// Registra un callback que el motor dispararà cuando la pista actual acabi de
+// drenar (times == 0 + stream buit). S'executa al mismo thread que
+// Audio::update (render loop); los consumidors no poden fer I/O blocant.
+void Audio::setOnMusicEnded(std::function<void()> callback) {
+    if (engine_) { engine_->setOnMusicEnded(std::move(callback)); }
 }
 
-// Consulta directamente el estado real de la música en jailaudio
-auto Audio::getRealMusicState() -> MusicState {
-    JA_Music_state ja_state = JA_GetMusicState();
-    switch (ja_state) {
-        case JA_MUSIC_PLAYING:
+// Resol el nom contra el cache de recursos i retorna la duración pre-calculada
+// al `loadMusic`. 0 si la pista no existeix — así el caller pot decidir
+// fallback (p. ex. usar un timeout fix) sin haver de propagar errors.
+auto Audio::getMusicDurationMs(const std::string& name) -> int {
+    auto* music = AudioResource::getMusic(name);
+    return (music != nullptr) ? music->duration_ms : 0;
+}
+
+// Consulta directament l'estat a Ja y el projecta al subconjunt d'estats que
+// exposa Audio (INVALID/DISABLED de Ja col·lapsen a STOPPED — la capa d'usuari
+// solo vol saber si está sonant, pausat o parat).
+auto Audio::getMusicState() -> MusicState {
+    if (!instance || !instance->engine_) { return MusicState::STOPPED; }
+    switch (instance->engine_->getMusicState()) {
+        case Ja::MusicState::PLAYING:
             return MusicState::PLAYING;
-        case JA_MUSIC_PAUSED:
+        case Ja::MusicState::PAUSED:
             return MusicState::PAUSED;
-        case JA_MUSIC_STOPPED:
-        case JA_MUSIC_INVALID:
-        case JA_MUSIC_DISABLED:
+        case Ja::MusicState::STOPPED:
+        case Ja::MusicState::INVALID:
         default:
             return MusicState::STOPPED;
     }
 }
 
-// Establece el volumen de los sonidos
-void Audio::setSoundVolume(float sound_volume, Group group) const {
-    if (sound_enabled_) {
-        sound_volume = std::clamp(sound_volume, MIN_VOLUME, MAX_VOLUME);
-        const float CONVERTED_VOLUME = sound_volume * Options::audio.volume;
-        JA_SetSoundVolume(CONVERTED_VOLUME, static_cast<int>(group));
-    }
+// Aplica el gate master (enabled_) + el gate del canal (sound/music_enabled_)
+// i retorna el volum escalat pel master config_.volume. 0 si algun gate está
+// tancat. Así los dos setters comparteixen la misma política.
+auto Audio::effectiveVolume(float volume, bool channel_enabled) const -> float {
+    volume = std::clamp(volume, MIN_VOLUME, MAX_VOLUME);
+    return (enabled_ && channel_enabled) ? volume * config_.volume : 0.0F;
 }
 
-// Establece el volumen de la música
-void Audio::setMusicVolume(float music_volume) const {
-    if (music_enabled_) {
-        music_volume = std::clamp(music_volume, MIN_VOLUME, MAX_VOLUME);
-        const float CONVERTED_VOLUME = music_volume * Options::audio.volume;
-        JA_SetMusicVolume(CONVERTED_VOLUME);
-    }
+// Estableix el volum dels sons (float 0.0..1.0)
+void Audio::setSoundVolume(float sound_volume, Group group) {
+    engine_->setSoundVolume(effectiveVolume(sound_volume, sound_enabled_), static_cast<int>(group));
 }
 
-// Aplica la configuración
-void Audio::applySettings() {
-    enable(Options::audio.enabled);
+// Estableix el volum de la música (float 0.0..1.0)
+void Audio::setMusicVolume(float music_volume) {
+    engine_->setMusicVolume(effectiveVolume(music_volume, music_enabled_));
 }
 
-// Establecer estado general
+// Aplica una nueva configuración (substitueix la config cachejada i reaplica enables/volums)
+void Audio::applySettings(const Config& config) {
+    config_ = config;
+    sound_enabled_ = config_.sound_enabled;
+    music_enabled_ = config_.music_enabled;
+    enable(config_.enabled);
+}
+
+// Estableix l'estat general
 void Audio::enable(bool value) {
     enabled_ = value;
 
-    setSoundVolume(enabled_ ? Options::audio.sound.volume : MIN_VOLUME);
-    setMusicVolume(enabled_ ? Options::audio.music.volume : MIN_VOLUME);
+    setSoundVolume(enabled_ ? config_.sound_volume : MIN_VOLUME);
+    setMusicVolume(enabled_ ? config_.music_volume : MIN_VOLUME);
 }
 
-// Inicializa SDL Audio
+// Estableix l'estat dels sons i reaplica el volum porque los canals actius
+// responguin a l'instant (evita que el toggle solo surti efecte al pròxim
+// setSoundVolume explícit).
+void Audio::enableSound(bool value) {
+    sound_enabled_ = value;
+    setSoundVolume(config_.sound_volume);
+}
+
+// Estableix l'estat de la música i reaplica el volum per la misma raó.
+void Audio::enableMusic(bool value) {
+    music_enabled_ = value;
+    setMusicVolume(config_.music_volume);
+}
+
+// Inicialitza SDL Audio y el motor Ja::Engine owned.
 void Audio::initSDLAudio() {
     if (!SDL_Init(SDL_INIT_AUDIO)) {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_AUDIO could not initialize! SDL Error: %s", SDL_GetError());
-    } else {
-        JA_Init(FREQUENCY, SDL_AUDIO_S16LE, 2);
-        enable(Options::audio.enabled);
-
-        std::cout << "\n** AUDIO SYSTEM **\n";
-        std::cout << "Audio system initialized successfully\n";
+        std::fprintf(stderr, "Audio: SDL_AUDIO could not initialize! SDL Error: %s\n", SDL_GetError());
+        return;
     }
-}
\ No newline at end of file
+    engine_ = std::make_unique<Ja::Engine>(Defaults::Audio::FREQUENCY, Defaults::Audio::FORMAT, Defaults::Audio::CHANNELS);
+    sound_enabled_ = config_.sound_enabled;
+    music_enabled_ = config_.music_enabled;
+    enable(config_.enabled);
+}
diff --git a/source/core/audio/audio.hpp b/source/core/audio/audio.hpp
index 16ff733..957b383 100644
--- a/source/core/audio/audio.hpp
+++ b/source/core/audio/audio.hpp
@@ -1,97 +1,163 @@
 #pragma once
 
-#include <string>   // Para string
-#include <utility>  // Para move
+#include <cmath>       // Para std::lround
+#include <cstdint>     // Para int8_t, uint8_t
+#include <functional>  // Para std::function
+#include <memory>      // Para std::unique_ptr
+#include <string>      // Para string
+#include <utility>     // Para move
 
-// --- Clase Audio: gestor de audio (singleton) ---
+// Forward-declares per no incloure core/audio/jail_audio.hpp al header. Els
+// tres símbols (Music/Sound para el punter que exposa la API i Engine per al
+// std::unique_ptr<Engine> membre) s'usen solo per punter al header, así que
+// el forward-decl basta. El ~Audio() en .cpp veu la definició completa i
+// instancia correctament el dtor de l'unique_ptr.
+namespace Ja {
+    class Engine;
+    struct Music;
+    struct Sound;
+}  // namespace Ja
+
+// --- Clase Audio: gestor d'àudio (singleton) ---
+// Port del subsistema d'àudio del projecte ../aee, desacoblat d'Options:
+// la configuración entra per la struct Audio::Config a init()/applySettings(),
+// en lloc de llegir directament Options::audio. Això deixa audio.cpp independent
+// del layout d'Options i permet substituir la font de configuración.
+//
+// Els volums es manegen internament como a float 0.0–1.0; la capa de
+// presentació (menús, notificacions) usa las helpers toPercent/fromPercent
+// per mostrar 0–100 a l'usuari.
 class Audio {
-    public:
-        // --- Enums ---
-        enum class Group : int {
-            ALL = -1,      // Todos los grupos
-            GAME = 0,      // Sonidos del juego
-            INTERFACE = 1  // Sonidos de la interfaz
-        };
+   public:
+    // --- Configuración injectada (Options la construeix via buildAudioConfig) ---
+    struct Config {
+        bool enabled{true};
+        float volume{1.0F};  // Master 0..1
+        bool music_enabled{true};
+        float music_volume{0.8F};
+        bool sound_enabled{true};
+        float sound_volume{1.0F};
+    };
 
-        enum class MusicState {
-            PLAYING,  // Reproduciendo música
-            PAUSED,   // Música pausada
-            STOPPED,  // Música detenida
-        };
+    // --- Enums ---
+    enum class Group : std::int8_t {
+        ALL = -1,      // Tots los grups
+        GAME = 0,      // Sons del joc
+        INTERFACE = 1  // Sons de la interfície
+    };
 
-        // --- Constantes ---
-        static constexpr float MAX_VOLUME = 1.0F;  // Volumen máximo
-        static constexpr float MIN_VOLUME = 0.0F;  // Volumen mínimo
-        static constexpr int FREQUENCY = 48000;    // Frecuencia de audio
+    enum class MusicState : std::uint8_t {
+        PLAYING,  // Reproduint música
+        PAUSED,   // Música pausada
+        STOPPED,  // Música aturada
+    };
 
-        // --- Singleton ---
-        static void init();                               // Inicializa el objeto Audio
-        static void destroy();                            // Libera el objeto Audio
-        static auto get() -> Audio*;                      // Obtiene el puntero al objeto Audio
-        Audio(const Audio&) = delete;                     // Evitar copia
-        auto operator=(const Audio&) -> Audio& = delete;  // Evitar asignación
+    // --- Constants ---
+    static constexpr float MAX_VOLUME = 1.0F;  // Volum màxim (float 0..1)
+    static constexpr float MIN_VOLUME = 0.0F;  // Volum mínim (float 0..1)
 
-        static void update();  // Actualización del sistema de audio
+    // --- Singleton ---
+    static void init(const Config& config);  // Inicialitza con la configuración rebuda
+    static void destroy();                   // Allibera l'objecte Audio
+    static auto get() -> Audio*;             // Obté el punter a l'objecte Audio
+    ~Audio();                                // Destructor (públic para std::unique_ptr)
+    Audio(const Audio&) = delete;            // Evitar còpia
+    Audio(Audio&&) = delete;
+    auto operator=(const Audio&) -> Audio& = delete;  // Evitar assignació
+    auto operator=(Audio&&) -> Audio& = delete;
 
-        // --- Control de música ---
-        void playMusic(const std::string& name, int loop = -1);  // Reproducir música en bucle
-        void pauseMusic();                                       // Pausar reproducción de música
-        void resumeMusic();                                      // Continua la música pausada
-        void stopMusic();                                        // Detener completamente la música
-        void fadeOutMusic(int milliseconds) const;               // Fundido de salida de la música
+    static void update();  // Actualització del sistema d'àudio
 
-        // --- Control de sonidos ---
-        void playSound(const std::string& name, Group group = Group::GAME) const;   // Reproducir sonido puntual por nombre
-        void playSound(struct JA_Sound_t* sound, Group group = Group::GAME) const;  // Reproducir sonido puntual por puntero
-        void stopAllSounds() const;                                                 // Detener todos los sonidos
+    // --- Control de música ---
+    void playMusic(const std::string& name, int loop = -1, int crossfade_ms = 0);  // Reproduir música per nom (amb crossfade opcional)
+    void playMusic(Ja::Music* music, int loop = -1, int crossfade_ms = 0);         // Reproduir música per punter (amb crossfade opcional)
+    void pauseMusic();                                                             // Pausar la reproducció de música
+    void resumeMusic();                                                            // Continua la música pausada
+    void stopMusic();                                                              // Aturar completament la música
+    void fadeOutMusic(int milliseconds);                                           // Fosa de sortida de la música (muta globals de Ja)
+    void setOnMusicEnded(std::function<void()> callback);                          // Callback disparat cuando la pista actual acaba de drenar (CONV-03)
+    // Multiplicador de velocitat de la música actual. 1.0 = normal,
+    // 1.5 = un 50% més ràpid (efecte "chipmunk" — también puja el to).
+    // Es reseteja a 1.0 implícitament a cada `playMusic`. No-op si no
+    // hay música activa.
+    void setMusicSpeed(float ratio);
 
-        // --- Control de volumen ---
-        void setSoundVolume(float volume, Group group = Group::ALL) const;  // Ajustar volumen de efectos
-        void setMusicVolume(float volume) const;                            // Ajustar volumen de música
+    // --- Control de sons ---
+    void playSound(const std::string& name, Group group = Group::GAME);  // Reproduir so puntual per nom (muta globals de Ja)
+    void playSound(Ja::Sound* sound, Group group = Group::GAME);         // Reproduir so puntual per punter (muta globals de Ja)
+    // Reprodueix un so con la velocitat (i to) escalats per `speed`:
+    // 1.0 = normal, 0.95 ≈ -5% (més greu i lent), 1.05 ≈ +5% (més
+    // agut i ràpid). Mateixa semàntica que `setMusicSpeed`. Útil per a
+    // variacions subtils que eviten la fatiga d'escoltar el mismo
+    // sample idèntic (p.ex. obertures de sarcòfag, picks d'ítems).
+    void playSound(const std::string& name, Group group, float speed);
+    // Reprodueix un so processat per un efecte definit a data/config/sounds.yaml
+    // (preset_name busca a SoundEffectsConfig). Si el preset no existeix
+    // o el motor está al sin de canals con efecte, fa fallback a playSound
+    // sec — l'usuari sent el so igualment, sin la cua.
+    void playSoundWithEcho(const std::string& name, const std::string& preset_name, Group group = Group::GAME);
+    void playSoundWithReverb(const std::string& name, const std::string& preset_name, Group group = Group::GAME);
+    void stopAllSounds();  // Aturar tots los sons (muta globals de Ja)
 
-        // --- Configuración general ---
-        void enable(bool value);                        // Establecer estado general
-        void toggleEnabled() { enabled_ = !enabled_; }  // Alternar estado general
-        void applySettings();                           // Aplica la configuración
+    // --- Control de volum (API interna: float 0.0..1.0) ---
+    void setSoundVolume(float volume, Group group = Group::ALL);  // Ajusta el volum dels efectes
+    void setMusicVolume(float volume);                            // Ajusta el volum de la música
 
-        // --- Configuración de sonidos ---
-        void enableSound() { sound_enabled_ = true; }             // Habilitar sonidos
-        void disableSound() { sound_enabled_ = false; }           // Deshabilitar sonidos
-        void enableSound(bool value) { sound_enabled_ = value; }  // Establecer estado de sonidos
-        void toggleSound() { sound_enabled_ = !sound_enabled_; }  // Alternar estado de sonidos
+    // --- Helpers de conversió para la capa de presentació ---
+    // UI (menús, notificacions) manega enters 0..100; internament viu float 0..1.
+    // No són constexpr porque std::lround no ho es en C++20; s'usen en runtime.
+    static auto toPercent(float volume) -> int {
+        return static_cast<int>(std::lround(volume * 100.0F));
+    }
+    static auto fromPercent(int percent) -> float {
+        return static_cast<float>(percent) / 100.0F;
+    }
 
-        // --- Configuración de música ---
-        void enableMusic() { music_enabled_ = true; }             // Habilitar música
-        void disableMusic() { music_enabled_ = false; }           // Deshabilitar música
-        void enableMusic(bool value) { music_enabled_ = value; }  // Establecer estado de música
-        void toggleMusic() { music_enabled_ = !music_enabled_; }  // Alternar estado de música
+    // --- Configuración general ---
+    void enable(bool value);                     // Estableix l'estat general (reaplica volums)
+    void toggleEnabled() { enable(!enabled_); }  // Alterna l'estat general (reaplica volums)
+    void applySettings(const Config& config);    // Aplica una nueva configuración
 
-        // --- Consultas de estado ---
-        [[nodiscard]] auto isEnabled() const -> bool { return enabled_; }
-        [[nodiscard]] auto isSoundEnabled() const -> bool { return sound_enabled_; }
-        [[nodiscard]] auto isMusicEnabled() const -> bool { return music_enabled_; }
-        [[nodiscard]] auto getMusicState() const -> MusicState { return music_.state; }
-        [[nodiscard]] static auto getRealMusicState() -> MusicState;
-        [[nodiscard]] auto getCurrentMusicName() const -> const std::string& { return music_.name; }
+    // --- Configuración de sons ---
+    void enableSound(bool value);                         // Estableix l'estat dels sons (reaplica volum)
+    void toggleSound() { enableSound(!sound_enabled_); }  // Alterna l'estat dels sons (reaplica volum)
 
-    private:
-        // --- Tipos anidados ---
-        struct Music {
-                MusicState state{MusicState::STOPPED};  // Estado actual de la música
-                std::string name;                       // Última pista de música reproducida
-                bool loop{false};                       // Indica si se reproduce en bucle
-        };
+    // --- Configuración de música ---
+    void enableMusic(bool value);                         // Estableix l'estat de la música (reaplica volum)
+    void toggleMusic() { enableMusic(!music_enabled_); }  // Alterna l'estat de la música (reaplica volum)
 
-        // --- Métodos ---
-        Audio();              // Constructor privado
-        ~Audio();             // Destructor privado
-        void initSDLAudio();  // Inicializa SDL Audio
+    // --- Consultes d'estat ---
+    [[nodiscard]] auto isEnabled() const -> bool { return enabled_; }
+    [[nodiscard]] auto isSoundEnabled() const -> bool { return sound_enabled_; }
+    [[nodiscard]] auto isMusicEnabled() const -> bool { return music_enabled_; }
+    [[nodiscard]] static auto getMusicState() -> MusicState;  // Estat real consultat a Ja::
+    [[nodiscard]] auto getCurrentMusicName() const -> const std::string& { return music_.name; }
+    // Duración de la pista resolta per nom (mil·lisegons). 0 si la pista no
+    // existeix al cache de recursos o si el seu header OGG no permet
+    // calcular-la. Pensat para clients que necessiten un timeline
+    // determinista (p. ex. RoomFsm) sin dependre de callbacks de fi.
+    [[nodiscard]] static auto getMusicDurationMs(const std::string& name) -> int;
 
-        // --- Variables miembro ---
-        static Audio* instance;  // Instancia única de Audio
+   private:
+    // --- Tipus anidats ---
+    struct Music {
+        std::string name;  // Última pista de música reproduïda (buida si es va passar per punter sin filename)
+        bool loop{false};  // Si el play actual es en bucle
+    };
 
-        Music music_;               // Estado de la música
-        bool enabled_{true};        // Estado general del audio
-        bool sound_enabled_{true};  // Estado de los efectos de sonido
-        bool music_enabled_{true};  // Estado de la música
-};
\ No newline at end of file
+    // --- Mètodes ---
+    explicit Audio(const Config& config);                                                   // Constructor privat: rep la config
+    void initSDLAudio();                                                                    // Inicialitza SDL Audio
+    void playMusicInternal(Ja::Music* music, int loop, int crossfade_ms);                   // Camí comú dels dos overloads de playMusic
+    [[nodiscard]] auto effectiveVolume(float volume, bool channel_enabled) const -> float;  // Gate master+channel: 0 si algun está off, clamp 0..1 altrament
+
+    // --- Variables membre ---
+    static std::unique_ptr<Audio> instance;  // Instància única d'Audio
+
+    std::unique_ptr<Ja::Engine> engine_;  // Motor de baix nivell (owned); viu mentre Audio viu.
+    Config config_{};                     // Configuración injectada (volums, enables)
+    Music music_;                         // Estat de la música (nom + loop cachejats)
+    bool enabled_{true};                  // Estat general de l'àudio
+    bool sound_enabled_{true};            // Estat dels efectes de so
+    bool music_enabled_{true};            // Estat de la música
+};
diff --git a/source/core/audio/audio_adapter.cpp b/source/core/audio/audio_adapter.cpp
new file mode 100644
index 0000000..e67d744
--- /dev/null
+++ b/source/core/audio/audio_adapter.cpp
@@ -0,0 +1,99 @@
+// audio_adapter.cpp - Implementación de AudioResource para orni_attack
+// © 2025 Orni Attack
+//
+// Implementa AudioResource::getMusic / getSound delegando a
+// Resource::Helper::loadFile (que abstrae el resources.pack y el fallback
+// a filesystem). Cache local de Ja::Music* / Ja::Sound* con lazy load:
+// cada recurso se carga la primera vez que se pide y se mantiene vivo
+// hasta el shutdown.
+
+#include "core/audio/audio_adapter.hpp"
+
+#include <cstdint>
+#include <iostream>
+#include <memory>
+#include <string>
+#include <unordered_map>
+
+#include "core/audio/jail_audio.hpp"
+#include "core/resources/resource_helper.hpp"
+
+namespace {
+
+// Cachés locales: indexados por nombre lógico ("title.ogg", "effects/laser_shoot.wav", etc.)
+// Mantienen ownership con unique_ptr; se liberan al salir del programa.
+std::unordered_map<std::string, std::unique_ptr<Ja::Music>>& musicCache() {
+    static std::unordered_map<std::string, std::unique_ptr<Ja::Music>> cache;
+    return cache;
+}
+
+std::unordered_map<std::string, std::unique_ptr<Ja::Sound>>& soundCache() {
+    static std::unordered_map<std::string, std::unique_ptr<Ja::Sound>> cache;
+    return cache;
+}
+
+// Normaliza el nombre añadiendo la subcarpeta correspondiente si no la trae:
+//   "title.ogg"            -> "music/title.ogg"
+//   "music/title.ogg"      -> "music/title.ogg"
+//   "effects/laser.wav"    -> "sounds/effects/laser.wav"
+std::string normalizeMusicPath(const std::string& name) {
+    return (name.rfind("music/", 0) == 0) ? name : "music/" + name;
+}
+
+std::string normalizeSoundPath(const std::string& name) {
+    return (name.rfind("sounds/", 0) == 0) ? name : "sounds/" + name;
+}
+
+}  // namespace
+
+namespace AudioResource {
+
+auto getMusic(const std::string& name) -> Ja::Music* {
+    auto& cache = musicCache();
+    if (auto it = cache.find(name); it != cache.end()) {
+        return it->second.get();
+    }
+
+    const std::string path = normalizeMusicPath(name);
+    auto bytes = Resource::Helper::loadFile(path);
+    if (bytes.empty()) {
+        std::cerr << "[AudioResource] no se ha podido cargar música: " << path << "\n";
+        return nullptr;
+    }
+
+    Ja::Music* raw = Ja::loadMusic(bytes.data(), static_cast<std::uint32_t>(bytes.size()), name.c_str());
+    if (raw == nullptr) {
+        std::cerr << "[AudioResource] decodificación de música falló: " << path << "\n";
+        return nullptr;
+    }
+
+    cache.emplace(name, std::unique_ptr<Ja::Music>(raw));
+    std::cout << "[AudioResource] música cargada: " << path << "\n";
+    return raw;
+}
+
+auto getSound(const std::string& name) -> Ja::Sound* {
+    auto& cache = soundCache();
+    if (auto it = cache.find(name); it != cache.end()) {
+        return it->second.get();
+    }
+
+    const std::string path = normalizeSoundPath(name);
+    auto bytes = Resource::Helper::loadFile(path);
+    if (bytes.empty()) {
+        std::cerr << "[AudioResource] no se ha podido cargar sonido: " << path << "\n";
+        return nullptr;
+    }
+
+    Ja::Sound* raw = Ja::loadSound(bytes.data(), static_cast<std::uint32_t>(bytes.size()));
+    if (raw == nullptr) {
+        std::cerr << "[AudioResource] decodificación de sonido falló: " << path << "\n";
+        return nullptr;
+    }
+
+    cache.emplace(name, std::unique_ptr<Ja::Sound>(raw));
+    std::cout << "[AudioResource] sonido cargado: " << path << "\n";
+    return raw;
+}
+
+}  // namespace AudioResource
diff --git a/source/core/audio/audio_adapter.hpp b/source/core/audio/audio_adapter.hpp
new file mode 100644
index 0000000..1afccfc
--- /dev/null
+++ b/source/core/audio/audio_adapter.hpp
@@ -0,0 +1,19 @@
+#pragma once
+
+// --- Audio Resource Adapter ---
+// Este archivo exposa una interfície comuna a Audio per obtenir Ja::Music* /
+// Ja::Sound* per nom. Cada projecte la implementa en audio_adapter.cpp delegant
+// al seu singleton de recursos (Resource::Cache::get(), ...). Así audio.hpp
+// i audio.cpp es poden compartir entre projectes.
+
+#include <string>  // Para string
+
+namespace Ja {
+    struct Music;
+    struct Sound;
+}  // namespace Ja
+
+namespace AudioResource {
+    auto getMusic(const std::string& name) -> Ja::Music*;
+    auto getSound(const std::string& name) -> Ja::Sound*;
+}  // namespace AudioResource
diff --git a/source/core/audio/audio_cache.cpp b/source/core/audio/audio_cache.cpp
deleted file mode 100644
index e7e6164..0000000
--- a/source/core/audio/audio_cache.cpp
+++ /dev/null
@@ -1,142 +0,0 @@
-// audio_cache.cpp - Implementació del caché de sons i música
-// © 2025 Port a C++20 con SDL3
-
-#include "core/audio/audio_cache.hpp"
-
-#include <iostream>
-
-#include "core/resources/resource_helper.hpp"
-
-// Inicialización de variables estàtiques
-std::unordered_map<std::string, JA_Sound_t*> AudioCache::sounds_;
-std::unordered_map<std::string, JA_Music_t*> AudioCache::musics_;
-std::string AudioCache::sounds_base_path_ = "data/sounds/";
-std::string AudioCache::music_base_path_ = "data/music/";
-
-JA_Sound_t* AudioCache::getSound(const std::string& name) {
-    // Cache hit
-    auto it = sounds_.find(name);
-    if (it != sounds_.end()) {
-        std::cout << "[AudioCache] Sound cache hit: " << name << std::endl;
-        return it->second;
-    }
-
-    // Normalize path: "laser_shoot.wav" → "sounds/laser_shoot.wav"
-    std::string normalized = name;
-    if (normalized.find("sounds/") != 0) {
-        normalized = "sounds/" + normalized;
-    }
-
-    // Load from resource system
-    std::vector<uint8_t> data = Resource::Helper::loadFile(normalized);
-    if (data.empty()) {
-        std::cerr << "[AudioCache] Error: no s'ha pogut load " << normalized << std::endl;
-        return nullptr;
-    }
-
-    // Load sound from memory
-    JA_Sound_t* sound = JA_LoadSound(data.data(), static_cast<uint32_t>(data.size()));
-    if (sound == nullptr) {
-        std::cerr << "[AudioCache] Error: no s'ha pogut decodificar " << normalized
-                  << std::endl;
-        return nullptr;
-    }
-
-    std::cout << "[AudioCache] Sound loaded: " << normalized << std::endl;
-    sounds_[name] = sound;
-    return sound;
-}
-
-JA_Music_t* AudioCache::getMusic(const std::string& name) {
-    // Cache hit
-    auto it = musics_.find(name);
-    if (it != musics_.end()) {
-        std::cout << "[AudioCache] Music cache hit: " << name << std::endl;
-        return it->second;
-    }
-
-    // Normalize path: "title.ogg" → "music/title.ogg"
-    std::string normalized = name;
-    if (normalized.find("music/") != 0) {
-        normalized = "music/" + normalized;
-    }
-
-    // Load from resource system
-    std::vector<uint8_t> data = Resource::Helper::loadFile(normalized);
-    if (data.empty()) {
-        std::cerr << "[AudioCache] Error: no s'ha pogut load " << normalized << std::endl;
-        return nullptr;
-    }
-
-    // Load music from memory
-    JA_Music_t* music = JA_LoadMusic(data.data(), static_cast<uint32_t>(data.size()));
-    if (music == nullptr) {
-        std::cerr << "[AudioCache] Error: no s'ha pogut decodificar " << normalized
-                  << std::endl;
-        return nullptr;
-    }
-
-    std::cout << "[AudioCache] Music loaded: " << normalized << std::endl;
-    musics_[name] = music;
-    return music;
-}
-
-void AudioCache::clear() {
-    std::cout << "[AudioCache] Clearing cache (" << sounds_.size() << " sounds, "
-              << musics_.size() << " music)" << std::endl;
-
-    // Liberar memoria de sonidos
-    for (auto& [name, sound] : sounds_) {
-        if (sound && sound->buffer) {
-            SDL_free(sound->buffer);
-        }
-        delete sound;
-    }
-    sounds_.clear();
-
-    // Liberar memoria de música
-    for (auto& [name, music] : musics_) {
-        if (music && music->buffer) {
-            SDL_free(music->buffer);
-        }
-        if (music && music->filename) {
-            free(music->filename);
-        }
-        delete music;
-    }
-    musics_.clear();
-}
-
-size_t AudioCache::getSoundCacheSize() { return sounds_.size(); }
-
-size_t AudioCache::getMusicCacheSize() { return musics_.size(); }
-
-std::string AudioCache::resolveSoundPath(const std::string& name) {
-    // Si es un path absoluto (comienza con '/'), usarlo directamente
-    if (!name.empty() && name[0] == '/') {
-        return name;
-    }
-
-    // Si ya contiene el prefix base_path, usarlo directamente
-    if (name.find(sounds_base_path_) == 0) {
-        return name;
-    }
-
-    // Caso contrario, añadir base_path
-    return sounds_base_path_ + name;
-}
-
-std::string AudioCache::resolveMusicPath(const std::string& name) {
-    // Si es un path absoluto (comienza con '/'), usarlo directamente
-    if (!name.empty() && name[0] == '/') {
-        return name;
-    }
-
-    // Si ya contiene el prefix base_path, usarlo directamente
-    if (name.find(music_base_path_) == 0) {
-        return name;
-    }
-
-    // Caso contrario, añadir base_path
-    return music_base_path_ + name;
-}
diff --git a/source/core/audio/audio_cache.hpp b/source/core/audio/audio_cache.hpp
deleted file mode 100644
index 2381333..0000000
--- a/source/core/audio/audio_cache.hpp
+++ /dev/null
@@ -1,42 +0,0 @@
-// audio_cache.hpp - Caché simplificado de sonidos y música
-// © 2025 Port a C++20 con SDL3
-
-#pragma once
-
-#include <string>
-#include <unordered_map>
-
-#include "core/audio/jail_audio.hpp"
-
-// Caché estático de sonidos y música
-// Patrón inspirado en Graphics::ShapeLoader
-class AudioCache {
-    public:
-        // No instanciable (todo estático)
-        AudioCache() = delete;
-
-        // Obtener sonido (carga bajo demanda)
-        // Retorna puntero (nullptr si error)
-        static JA_Sound_t* getSound(const std::string& name);
-
-        // Obtener música (carga bajo demanda)
-        // Retorna puntero (nullptr si error)
-        static JA_Music_t* getMusic(const std::string& name);
-
-        // Limpiar caché (útil para debug/recarga)
-        static void clear();
-
-        // Estadísticas (debug)
-        static size_t getSoundCacheSize();
-        static size_t getMusicCacheSize();
-
-    private:
-        static std::unordered_map<std::string, JA_Sound_t*> sounds_;
-        static std::unordered_map<std::string, JA_Music_t*> musics_;
-        static std::string sounds_base_path_;  // "data/sounds/"
-        static std::string music_base_path_;   // "data/music/"
-
-        // Helpers privados
-        static std::string resolveSoundPath(const std::string& name);
-        static std::string resolveMusicPath(const std::string& name);
-};
diff --git a/source/core/audio/audio_effects.cpp b/source/core/audio/audio_effects.cpp
new file mode 100644
index 0000000..b012c88
--- /dev/null
+++ b/source/core/audio/audio_effects.cpp
@@ -0,0 +1,251 @@
+#include "core/audio/audio_effects.hpp"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+#include <iostream>
+
+#include "core/audio/jail_audio.hpp"
+
+namespace AudioEffects {
+
+    namespace {
+
+        // --- Caps de cua ---
+        constexpr float ECHO_TAIL_MS = 800.0F;
+        constexpr float REVERB_TAIL_MS = 1500.0F;
+
+        // --- Constants Freeverb ---
+        // Delays de comb i allpass tunats para 44.1 kHz; los reescalem per
+        // freqüència real de la font.
+        constexpr int COMB_REFERENCE_RATE = 44100;
+        constexpr std::array<int, 8> COMB_DELAYS_L = {1116, 1188, 1277, 1356, 1422, 1491, 1557, 1617};
+        constexpr std::array<int, 4> ALLPASS_DELAYS_L = {556, 441, 341, 225};
+        constexpr int STEREO_SPREAD = 23;
+
+        // Mapeig de Schroeder/Dattorro/Freeverb estàndard.
+        constexpr float FIXED_GAIN = 0.015F;
+        constexpr float SCALE_ROOM = 0.28F;
+        constexpr float OFFSET_ROOM = 0.7F;
+        constexpr float SCALE_DAMP = 0.4F;
+
+        // --- Decodificació a float -1..1 ---
+        // Suporta U8/S16, mono/estèreo. Mono es duplica a L i R (la cadena
+        // d'efectes treballa siempre con dos canals per simplicitat).
+        auto decodeToStereoFloat(const Ja::Sound& src, std::vector<float>& left, std::vector<float>& right) -> bool {
+            const auto& spec = src.spec;
+            const Uint8* buf = src.buffer.get();
+            if (buf == nullptr || src.length == 0) { return false; }
+
+            int bytes_per_sample = 0;
+            if (spec.format == SDL_AUDIO_S16) {
+                bytes_per_sample = 2;
+            } else if (spec.format == SDL_AUDIO_U8) {
+                bytes_per_sample = 1;
+            } else {
+                std::cerr << "[AudioEffects] formato de sonido no soportado (solo U8 o S16)\n";
+                return false;
+            }
+            if (spec.channels < 1 || spec.channels > 2) {
+                std::cerr << "[AudioEffects] el sonido debe ser mono o estéreo\n";
+                return false;
+            }
+
+            const std::size_t TOTAL_FRAMES = src.length / static_cast<std::size_t>(bytes_per_sample * spec.channels);
+            left.resize(TOTAL_FRAMES);
+            right.resize(TOTAL_FRAMES);
+
+            for (std::size_t i = 0; i < TOTAL_FRAMES; ++i) {
+                float sample_l = 0.0F;
+                float sample_r = 0.0F;
+                if (spec.format == SDL_AUDIO_S16) {
+                    const auto* p = reinterpret_cast<const std::int16_t*>(buf + (i * spec.channels * 2));
+                    sample_l = static_cast<float>(p[0]) / 32768.0F;
+                    sample_r = (spec.channels == 2) ? static_cast<float>(p[1]) / 32768.0F : sample_l;
+                } else {  // U8
+                    const Uint8* p = buf + (i * spec.channels);
+                    sample_l = (static_cast<float>(p[0]) - 128.0F) / 128.0F;
+                    sample_r = (spec.channels == 2) ? (static_cast<float>(p[1]) - 128.0F) / 128.0F : sample_l;
+                }
+                left[i] = sample_l;
+                right[i] = sample_r;
+            }
+            return true;
+        }
+
+        // Empaqueta dos canals float (-1..1) a S16 entrellaçat.
+        void encodeStereoS16(const std::vector<float>& left, const std::vector<float>& right, std::vector<std::uint8_t>& out) {
+            const std::size_t LEN = left.size();
+            out.resize(LEN * 2 * sizeof(std::int16_t));
+            auto* dst = reinterpret_cast<std::int16_t*>(out.data());
+            for (std::size_t i = 0; i < LEN; ++i) {
+                const float L = std::clamp(left[i], -1.0F, 1.0F);
+                const float R = std::clamp(right[i], -1.0F, 1.0F);
+                dst[(i * 2) + 0] = static_cast<std::int16_t>(std::lround(L * 32767.0F));
+                dst[(i * 2) + 1] = static_cast<std::int16_t>(std::lround(R * 32767.0F));
+            }
+        }
+
+        // Reescala un delay de la taula de Freeverb para la freqüència real.
+        auto scaledDelay(int reference_delay, int rate) -> int {
+            const long SCALED = std::lround(static_cast<double>(reference_delay) * static_cast<double>(rate) / static_cast<double>(COMB_REFERENCE_RATE));
+            return std::max(1, static_cast<int>(SCALED));
+        }
+
+        // --- Filtres bàsics ---
+        struct Comb {
+            std::vector<float> buf;
+            std::size_t idx{0};
+            float feedback{0.0F};
+            float damp1{0.0F};
+            float damp2{1.0F};
+            float store{0.0F};
+
+            void init(int delay, float fb, float damping) {
+                buf.assign(static_cast<std::size_t>(delay), 0.0F);
+                idx = 0;
+                feedback = fb;
+                damp1 = damping;
+                damp2 = 1.0F - damping;
+                store = 0.0F;
+            }
+            auto tick(float in) -> float {
+                const float OUT = buf[idx];
+                store = (OUT * damp2) + (store * damp1);
+                buf[idx] = in + (store * feedback);
+                idx = (idx + 1) % buf.size();
+                return OUT;
+            }
+        };
+
+        struct Allpass {
+            std::vector<float> buf;
+            std::size_t idx{0};
+
+            void init(int delay) {
+                buf.assign(static_cast<std::size_t>(delay), 0.0F);
+                idx = 0;
+            }
+            auto tick(float in) -> float {
+                const float BUFOUT = buf[idx];
+                const float OUT = -in + BUFOUT;
+                buf[idx] = in + (BUFOUT * 0.5F);
+                idx = (idx + 1) % buf.size();
+                return OUT;
+            }
+        };
+
+    }  // namespace
+
+    auto applyEcho(const Ja::Sound& src, const Ja::EchoParams& params) -> std::optional<ProcessedSound> {
+        std::vector<float> left;
+        std::vector<float> right;
+        if (!decodeToStereoFloat(src, left, right)) { return std::nullopt; }
+
+        const int RATE = src.spec.freq;
+        const int DELAY_SAMPLES = std::max(1, static_cast<int>(std::lround(params.delay_ms * 0.001F * static_cast<float>(RATE))));
+        const auto TAIL_SAMPLES = static_cast<std::size_t>(std::lround(ECHO_TAIL_MS * 0.001F * static_cast<float>(RATE)));
+
+        const float FEEDBACK = std::clamp(params.feedback, 0.0F, 0.95F);
+        const float WET = std::clamp(params.wet, 0.0F, 1.0F);
+        const float DRY = 1.0F - WET;
+
+        const std::size_t INPUT_LEN = left.size();
+        const std::size_t TOTAL_LEN = INPUT_LEN + TAIL_SAMPLES;
+
+        std::vector<float> ring_l(static_cast<std::size_t>(DELAY_SAMPLES), 0.0F);
+        std::vector<float> ring_r(static_cast<std::size_t>(DELAY_SAMPLES), 0.0F);
+        std::size_t cursor = 0;
+
+        std::vector<float> out_l(TOTAL_LEN);
+        std::vector<float> out_r(TOTAL_LEN);
+
+        for (std::size_t i = 0; i < TOTAL_LEN; ++i) {
+            const float IN_L = (i < INPUT_LEN) ? left[i] : 0.0F;
+            const float IN_R = (i < INPUT_LEN) ? right[i] : 0.0F;
+
+            const float DELAYED_L = ring_l[cursor];
+            const float DELAYED_R = ring_r[cursor];
+
+            out_l[i] = (DRY * IN_L) + (WET * DELAYED_L);
+            out_r[i] = (DRY * IN_R) + (WET * DELAYED_R);
+
+            ring_l[cursor] = IN_L + (DELAYED_L * FEEDBACK);
+            ring_r[cursor] = IN_R + (DELAYED_R * FEEDBACK);
+            cursor = (cursor + 1) % static_cast<std::size_t>(DELAY_SAMPLES);
+        }
+
+        ProcessedSound result;
+        result.spec = SDL_AudioSpec{.format = SDL_AUDIO_S16, .channels = 2, .freq = RATE};
+        encodeStereoS16(out_l, out_r, result.bytes);
+        return result;
+    }
+
+    auto applyReverb(const Ja::Sound& src, const Ja::ReverbParams& params) -> std::optional<ProcessedSound> {
+        std::vector<float> left;
+        std::vector<float> right;
+        if (!decodeToStereoFloat(src, left, right)) { return std::nullopt; }
+
+        const int RATE = src.spec.freq;
+        const auto TAIL_SAMPLES = static_cast<std::size_t>(std::lround(REVERB_TAIL_MS * 0.001F * static_cast<float>(RATE)));
+
+        const float ROOM_SIZE = std::clamp(params.room_size, 0.0F, 1.0F);
+        const float DAMPING = std::clamp(params.damping, 0.0F, 1.0F);
+        const float WET = std::clamp(params.wet, 0.0F, 1.0F);
+        const float DRY = 1.0F - WET;
+
+        const float FEEDBACK = (ROOM_SIZE * SCALE_ROOM) + OFFSET_ROOM;  // 0.7..0.98
+        const float DAMP1 = DAMPING * SCALE_DAMP;                       // 0..0.4
+
+        // Inicialitza los 8 comb filters per cada canal i los 4 allpass.
+        std::array<Comb, 8> comb_l;
+        std::array<Comb, 8> comb_r;
+        for (std::size_t i = 0; i < COMB_DELAYS_L.size(); ++i) {
+            comb_l[i].init(scaledDelay(COMB_DELAYS_L[i], RATE), FEEDBACK, DAMP1);
+            comb_r[i].init(scaledDelay(COMB_DELAYS_L[i] + STEREO_SPREAD, RATE), FEEDBACK, DAMP1);
+        }
+        std::array<Allpass, 4> allpass_l;
+        std::array<Allpass, 4> allpass_r;
+        for (std::size_t i = 0; i < ALLPASS_DELAYS_L.size(); ++i) {
+            allpass_l[i].init(scaledDelay(ALLPASS_DELAYS_L[i], RATE));
+            allpass_r[i].init(scaledDelay(ALLPASS_DELAYS_L[i] + STEREO_SPREAD, RATE));
+        }
+
+        const std::size_t INPUT_LEN = left.size();
+        const std::size_t TOTAL_LEN = INPUT_LEN + TAIL_SAMPLES;
+        std::vector<float> out_l(TOTAL_LEN);
+        std::vector<float> out_r(TOTAL_LEN);
+
+        for (std::size_t i = 0; i < TOTAL_LEN; ++i) {
+            const float IN_L = (i < INPUT_LEN) ? left[i] : 0.0F;
+            const float IN_R = (i < INPUT_LEN) ? right[i] : 0.0F;
+            const float MONO_INPUT = (IN_L + IN_R) * FIXED_GAIN;
+
+            // 8 comb filters en paral·lel, sumats.
+            float wet_l = 0.0F;
+            float wet_r = 0.0F;
+            for (std::size_t k = 0; k < comb_l.size(); ++k) {
+                wet_l += comb_l[k].tick(MONO_INPUT);
+                wet_r += comb_r[k].tick(MONO_INPUT);
+            }
+            // 4 allpass en sèrie.
+            for (std::size_t k = 0; k < allpass_l.size(); ++k) {
+                wet_l = allpass_l[k].tick(wet_l);
+                wet_r = allpass_r[k].tick(wet_r);
+            }
+
+            out_l[i] = (DRY * IN_L) + (WET * wet_l);
+            out_r[i] = (DRY * IN_R) + (WET * wet_r);
+        }
+
+        ProcessedSound result;
+        result.spec = SDL_AudioSpec{.format = SDL_AUDIO_S16, .channels = 2, .freq = RATE};
+        encodeStereoS16(out_l, out_r, result.bytes);
+        return result;
+    }
+
+}  // namespace AudioEffects
diff --git a/source/core/audio/audio_effects.hpp b/source/core/audio/audio_effects.hpp
new file mode 100644
index 0000000..6204405
--- /dev/null
+++ b/source/core/audio/audio_effects.hpp
@@ -0,0 +1,38 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+
+#include <cstdint>
+#include <optional>
+#include <vector>
+
+// Forward-declaració per no incloure jail_audio.hpp (cicle d'inclusió: este
+// header viu sota los params declarats a jail_audio.hpp, i alhora jail_audio
+// usa applyEcho/applyReverb).
+namespace Ja {
+    struct Sound;
+    struct EchoParams;
+    struct ReverbParams;
+}  // namespace Ja
+
+// Processadors d'efectes para sons puntuals. Reben un Ja::Sound (qualsevol
+// format suportat pel decodificador WAV: U8/S16, mono o estèreo) i tornen un
+// buffer PCM en S16 + el seu spec, llest per empenyer a un SDL_AudioStream.
+//
+// El buffer de sortida inclou la cua (decay) generada per l'efecte: per al
+// reverb, hasta a 1500 ms; para l'eco, hasta a 800 ms. Aquests caps eviten
+// allargar indefinidament la reproducció cuando los parámetros reinjecten mucho.
+//
+// Si el format del so d'origen no es pot processar, retornen std::nullopt
+// (el caller ha de fer fallback a reproducció seca).
+namespace AudioEffects {
+
+    struct ProcessedSound {
+        std::vector<std::uint8_t> bytes;  // PCM S16 entrellaçat (LRLRLR... si stereo)
+        SDL_AudioSpec spec;               // Format/canals/freqüència del buffer
+    };
+
+    [[nodiscard]] auto applyEcho(const Ja::Sound& src, const Ja::EchoParams& params) -> std::optional<ProcessedSound>;
+    [[nodiscard]] auto applyReverb(const Ja::Sound& src, const Ja::ReverbParams& params) -> std::optional<ProcessedSound>;
+
+}  // namespace AudioEffects
diff --git a/source/core/audio/jail_audio.cpp b/source/core/audio/jail_audio.cpp
new file mode 100644
index 0000000..8e50358
--- /dev/null
+++ b/source/core/audio/jail_audio.cpp
@@ -0,0 +1,645 @@
+#include "core/audio/jail_audio.hpp"
+
+#include <algorithm>
+#include <cassert>
+#include <cstdint>
+#include <cstdio>
+#include <memory>
+#include <optional>
+#include <vector>
+
+#include "core/audio/audio_effects.hpp"
+
+// Solo declaracions de stb_vorbis: STB_VORBIS_HEADER_ONLY omet el bloc
+// d'implementació. Les definicions las aporta source/external/stb_vorbis_impl.cpp
+// (TU aïllat porque clang-analyzer no dispari fals positius al nostre codi).
+#define STB_VORBIS_HEADER_ONLY
+// clang-format off
+// NOLINTNEXTLINE(bugprone-suspicious-include) -- stb_vorbis es single-file: la macro de dalt limita este TU a solo-declaracions; la implementació viu a external/stb_vorbis_impl.cpp.
+#include "external/stb_vorbis.c"
+// clang-format on
+
+namespace Ja {
+
+    // --- Streaming internals (file-scope constants) ---
+    namespace {
+        // Bytes-per-sample per canal (siempre s16)
+        constexpr int MUSIC_BYTES_PER_SAMPLE = 2;
+        // Quants shorts decodifiquem per crida a get_samples_short_interleaved.
+        // 8192 shorts = 4096 samples/channel en estèreo ≈ 85ms de so a 48kHz.
+        constexpr int MUSIC_CHUNK_SHORTS = 8192;
+        // Umbral d'audio per davant del cursor de reproducció. Mantenim ≥ 0.5 s a
+        // l'SDL_AudioStream per absorbir jitter de frame i evitar underruns.
+        constexpr float MUSIC_LOW_WATER_SECONDS = 0.5F;
+    }  // namespace
+
+    // --- Engine::active_ storage ---
+    Engine* Engine::active_ = nullptr;
+
+    auto Engine::active() noexcept -> Engine* { return active_; }
+
+    // --- Ctor/Dtor ---
+
+    Engine::Engine(const int freq, const SDL_AudioFormat format, const int num_channels) {
+        assert(active_ == nullptr && "Ja::Engine: més d'una instància activa no está suportat");
+        active_ = this;
+
+        audio_spec_ = {.format = format, .channels = num_channels, .freq = freq};
+        sdl_audio_device_ = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &audio_spec_);
+        if (sdl_audio_device_ == 0) { std::fprintf(stderr, "Ja::Engine: Failed to initialize SDL audio!\n"); }
+        for (auto& channel : channels_) { channel.state = ChannelState::FREE; }
+    }
+
+    Engine::~Engine() {
+        if (outgoing_music_.stream != nullptr) {
+            SDL_DestroyAudioStream(outgoing_music_.stream);
+            outgoing_music_.stream = nullptr;
+        }
+        if (sdl_audio_device_ != 0) { SDL_CloseAudioDevice(sdl_audio_device_); }
+        sdl_audio_device_ = 0;
+
+        if (active_ == this) { active_ = nullptr; }
+    }
+
+    // --- Helpers stateless (no toquen membres d'Engine) ---
+    namespace {
+
+        auto feedMusicChunk(Music* music) -> int {
+            if (music == nullptr || music->vorbis == nullptr || music->stream == nullptr) { return 0; }
+
+            short chunk[MUSIC_CHUNK_SHORTS];
+            const int NUM_CHANNELS = music->spec.channels;
+            const int SAMPLES_PER_CHANNEL = stb_vorbis_get_samples_short_interleaved(
+                music->vorbis,
+                NUM_CHANNELS,
+                static_cast<short*>(chunk),
+                MUSIC_CHUNK_SHORTS);
+            if (SAMPLES_PER_CHANNEL <= 0) { return 0; }
+
+            const int BYTES = SAMPLES_PER_CHANNEL * NUM_CHANNELS * MUSIC_BYTES_PER_SAMPLE;
+            SDL_PutAudioStreamData(music->stream, static_cast<const void*>(chunk), BYTES);
+            return SAMPLES_PER_CHANNEL;
+        }
+
+        void pumpMusic(Music* music) {
+            if (music == nullptr || music->vorbis == nullptr || music->stream == nullptr) { return; }
+
+            const int BYTES_PER_SECOND = music->spec.freq * music->spec.channels * MUSIC_BYTES_PER_SAMPLE;
+            const int LOW_WATER_BYTES = static_cast<int>(MUSIC_LOW_WATER_SECONDS * static_cast<float>(BYTES_PER_SECOND));
+
+            while (SDL_GetAudioStreamAvailable(music->stream) < LOW_WATER_BYTES) {
+                const int DECODED = feedMusicChunk(music);
+                if (DECODED > 0) { continue; }
+
+                // EOF: si queden loops, rebobinar; si no, tallar y deixar drenar.
+                if (music->times != 0) {
+                    stb_vorbis_seek_start(music->vorbis);
+                    if (music->times > 0) { music->times--; }
+                } else {
+                    break;
+                }
+            }
+        }
+
+        void preFillOutgoing(Music* music, const int duration_ms) {
+            if (music == nullptr || music->vorbis == nullptr || music->stream == nullptr) { return; }
+
+            const int BYTES_PER_SECOND = music->spec.freq * music->spec.channels * MUSIC_BYTES_PER_SAMPLE;
+            const int NEEDED_BYTES = static_cast<int>((static_cast<std::int64_t>(duration_ms) * BYTES_PER_SECOND) / 1000);
+
+            while (SDL_GetAudioStreamAvailable(music->stream) < NEEDED_BYTES) {
+                const int DECODED = feedMusicChunk(music);
+                if (DECODED <= 0) { break; }
+            }
+        }
+
+        // Retorna el progrés lineal [0..1] d'un fade. 1.0 vol dir completat. Única
+        // font de la corba del fade: si es vol canviar a logarítmica/quadràtica,
+        // s'edita aquí i afecta fade-in i fade-out alhora.
+        auto fadeProgress(const FadeState& fade) -> float {
+            if (fade.duration_ms <= 0) { return 1.0F; }
+            const Uint64 ELAPSED = SDL_GetTicks() - fade.start_time;
+            if (ELAPSED >= static_cast<Uint64>(fade.duration_ms)) { return 1.0F; }
+            return static_cast<float>(ELAPSED) / static_cast<float>(fade.duration_ms);
+        }
+
+    }  // namespace
+
+    void Engine::updateOutgoingFade() {
+        if (outgoing_music_.stream == nullptr || !outgoing_music_.fade.active) { return; }
+
+        // Mentre la fosa está activa, mantenim el stream con una reserva
+        // de samples per davant del cursor (mismo patró que pumpMusic
+        // para el current_music_). Así el stream no es buida ni cuando SDL
+        // drena més ràpid del previst en haver sounds bound a la misma
+        // device. Si l'OGG arriba a EOF, rebobina (la fosa pot ser més
+        // llarga que la pista).
+        if (outgoing_music_.music != nullptr && outgoing_music_.music->vorbis != nullptr) {
+            const Music& music = *outgoing_music_.music;
+            const int BYTES_PER_SECOND = music.spec.freq * music.spec.channels * MUSIC_BYTES_PER_SAMPLE;
+            const int LOW_WATER = static_cast<int>(MUSIC_LOW_WATER_SECONDS * static_cast<float>(BYTES_PER_SECOND));
+            while (SDL_GetAudioStreamAvailable(outgoing_music_.stream) < LOW_WATER) {
+                short chunk[MUSIC_CHUNK_SHORTS];
+                const int SAMPLES = stb_vorbis_get_samples_short_interleaved(
+                    music.vorbis,
+                    music.spec.channels,
+                    static_cast<short*>(chunk),
+                    MUSIC_CHUNK_SHORTS);
+                if (SAMPLES <= 0) {
+                    stb_vorbis_seek_start(music.vorbis);
+                    continue;
+                }
+                const int BYTES = SAMPLES * music.spec.channels * MUSIC_BYTES_PER_SAMPLE;
+                SDL_PutAudioStreamData(outgoing_music_.stream, static_cast<const void*>(chunk), BYTES);
+            }
+        }
+
+        const float PROGRESS = fadeProgress(outgoing_music_.fade);
+        if (PROGRESS >= 1.0F) {
+            SDL_DestroyAudioStream(outgoing_music_.stream);
+            outgoing_music_.stream = nullptr;
+            outgoing_music_.fade.active = false;
+            // Deixem el Vorbis del Music original en un estat conegut per
+            // a la pròxima reproducció. (playMusic también fa seek_start,
+            // pero fer-ho ací evita estats intermedis si algú consulta.)
+            if (outgoing_music_.music != nullptr && outgoing_music_.music->vorbis != nullptr) {
+                stb_vorbis_seek_start(outgoing_music_.music->vorbis);
+            }
+            outgoing_music_.music = nullptr;
+        } else {
+            SDL_SetAudioStreamGain(outgoing_music_.stream, outgoing_music_.fade.initial_volume * (1.0F - PROGRESS));
+        }
+    }
+
+    void Engine::updateIncomingFade() {
+        if (!incoming_fade_.active) { return; }
+
+        const float PROGRESS = fadeProgress(incoming_fade_);
+        if (PROGRESS >= 1.0F) {
+            incoming_fade_.active = false;
+            SDL_SetAudioStreamGain(current_music_->stream, music_volume_);
+        } else {
+            SDL_SetAudioStreamGain(current_music_->stream, music_volume_ * PROGRESS);
+        }
+    }
+
+    void Engine::updateCurrentMusic() {
+        if (current_music_ == nullptr || current_music_->state != MusicState::PLAYING) { return; }
+
+        updateIncomingFade();
+
+        pumpMusic(current_music_);
+        if (current_music_->times == 0 && SDL_GetAudioStreamAvailable(current_music_->stream) == 0) {
+            // La pista ha acabat de drenar naturalment. L'aturem primer (deixa
+            // l'engine en estat consistent) i entonces invoquem el callback;
+            // así un eventual playMusic des del callback comença net.
+            stopMusic();
+            if (on_music_ended_) { on_music_ended_(); }
+        }
+    }
+
+    void Engine::updateSoundChannels() {
+        for (int i = 0; i < MAX_SIMULTANEOUS_CHANNELS; ++i) {
+            if (channels_[i].state != ChannelState::PLAYING) { continue; }
+
+            if (channels_[i].times != 0) {
+                if (static_cast<Uint32>(SDL_GetAudioStreamAvailable(channels_[i].stream)) < (channels_[i].sound->length / 2)) {
+                    SDL_PutAudioStreamData(channels_[i].stream, channels_[i].sound->buffer.get(), channels_[i].sound->length);
+                    if (channels_[i].times > 0) { channels_[i].times--; }
+                }
+            } else if (SDL_GetAudioStreamAvailable(channels_[i].stream) == 0) {
+                stopChannel(i);
+            }
+        }
+    }
+
+    void Engine::stealCurrentIntoOutgoing(const int duration_ms) {
+        if (outgoing_music_.stream != nullptr) {
+            SDL_DestroyAudioStream(outgoing_music_.stream);
+            outgoing_music_.stream = nullptr;
+            outgoing_music_.fade.active = false;
+        }
+
+        if (current_music_ == nullptr || current_music_->state != MusicState::PLAYING || current_music_->stream == nullptr) {
+            return;
+        }
+
+        preFillOutgoing(current_music_, duration_ms);
+
+        outgoing_music_.stream = current_music_->stream;
+        // Guardem la referència al Music porque updateOutgoingFade puga
+        // seguir bombant Vorbis sin al stream durante tota la fosa. NO fem
+        // seek_start ací: la decompressió ha de continuar des d'on estava
+        // porque el so siga continu. El seek_start es farà cuando la fosa
+        // acabe (o cuando playMusic la interrompi via stopMusic).
+        outgoing_music_.music = current_music_;
+        outgoing_music_.fade = {
+            .active = true,
+            .start_time = SDL_GetTicks(),
+            .duration_ms = duration_ms,
+            .initial_volume = music_volume_,
+        };
+        current_music_->stream = nullptr;
+        current_music_->state = MusicState::STOPPED;
+    }
+
+    template <typename Fn>
+    void Engine::forEachTargetChannel(const int channel, Fn&& fn) {
+        if (channel == -1) {
+            for (auto& ch : channels_) { fn(ch); }
+        } else if (channel >= 0 && channel < MAX_SIMULTANEOUS_CHANNELS) {
+            fn(channels_[channel]);
+        }
+    }
+
+    // --- Engine public API ---
+
+    void Engine::update() {
+        updateOutgoingFade();
+        updateCurrentMusic();
+        updateSoundChannels();
+    }
+
+    void Engine::playMusic(Music* music, const int loop) {
+        if (music == nullptr || music->vorbis == nullptr) { return; }
+
+        stopMusic();
+
+        current_music_ = music;
+        current_music_->state = MusicState::PLAYING;
+        current_music_->times = loop;
+
+        stb_vorbis_seek_start(current_music_->vorbis);
+
+        current_music_->stream = SDL_CreateAudioStream(&current_music_->spec, &audio_spec_);
+        if (current_music_->stream == nullptr) {
+            std::fprintf(stderr, "Ja::Engine::playMusic: Failed to create audio stream!\n");
+            current_music_->state = MusicState::STOPPED;
+            return;
+        }
+        SDL_SetAudioStreamGain(current_music_->stream, music_volume_);
+
+        pumpMusic(current_music_);
+
+        if (!SDL_BindAudioStream(sdl_audio_device_, current_music_->stream)) {
+            std::fprintf(stderr, "Ja::Engine::playMusic: SDL_BindAudioStream failed!\n");
+        }
+    }
+
+    void Engine::setMusicSpeed(float ratio) {
+        if (current_music_ == nullptr || current_music_->stream == nullptr) { return; }
+        SDL_SetAudioStreamFrequencyRatio(current_music_->stream, ratio);
+    }
+
+    void Engine::pauseMusic() {
+        if (current_music_ == nullptr || current_music_->state != MusicState::PLAYING) { return; }
+
+        current_music_->state = MusicState::PAUSED;
+        SDL_UnbindAudioStream(current_music_->stream);
+    }
+
+    void Engine::resumeMusic() {
+        if (current_music_ == nullptr || current_music_->state != MusicState::PAUSED) { return; }
+
+        current_music_->state = MusicState::PLAYING;
+        SDL_BindAudioStream(sdl_audio_device_, current_music_->stream);
+    }
+
+    void Engine::stopMusic() {
+        if (outgoing_music_.stream != nullptr) {
+            SDL_DestroyAudioStream(outgoing_music_.stream);
+            outgoing_music_.stream = nullptr;
+            outgoing_music_.fade.active = false;
+            if (outgoing_music_.music != nullptr && outgoing_music_.music->vorbis != nullptr) {
+                stb_vorbis_seek_start(outgoing_music_.music->vorbis);
+            }
+            outgoing_music_.music = nullptr;
+        }
+        incoming_fade_.active = false;
+
+        if (current_music_ == nullptr || current_music_->state == MusicState::INVALID || current_music_->state == MusicState::STOPPED) { return; }
+
+        current_music_->state = MusicState::STOPPED;
+        if (current_music_->stream != nullptr) {
+            SDL_DestroyAudioStream(current_music_->stream);
+            current_music_->stream = nullptr;
+        }
+        if (current_music_->vorbis != nullptr) {
+            stb_vorbis_seek_start(current_music_->vorbis);
+        }
+    }
+
+    void Engine::fadeOutMusic(const int milliseconds) {
+        if (current_music_ == nullptr || current_music_->state != MusicState::PLAYING) { return; }
+
+        stealCurrentIntoOutgoing(milliseconds);
+        incoming_fade_.active = false;
+    }
+
+    void Engine::crossfadeMusic(Music* music, const int crossfade_ms, const int loop) {
+        if (music == nullptr || music->vorbis == nullptr) { return; }
+
+        stealCurrentIntoOutgoing(crossfade_ms);
+
+        current_music_ = music;
+        current_music_->state = MusicState::PLAYING;
+        current_music_->times = loop;
+
+        stb_vorbis_seek_start(current_music_->vorbis);
+        current_music_->stream = SDL_CreateAudioStream(&current_music_->spec, &audio_spec_);
+        if (current_music_->stream == nullptr) {
+            std::fprintf(stderr, "Ja::Engine::crossfadeMusic: Failed to create audio stream!\n");
+            current_music_->state = MusicState::STOPPED;
+            return;
+        }
+        SDL_SetAudioStreamGain(current_music_->stream, 0.0F);
+        pumpMusic(current_music_);
+        SDL_BindAudioStream(sdl_audio_device_, current_music_->stream);
+
+        incoming_fade_ = {
+            .active = true,
+            .start_time = SDL_GetTicks(),
+            .duration_ms = crossfade_ms,
+            .initial_volume = 0.0F,
+        };
+    }
+
+    auto Engine::getMusicState() const -> MusicState {
+        if (current_music_ == nullptr) { return MusicState::INVALID; }
+        return current_music_->state;
+    }
+
+    auto Engine::setMusicVolume(float volume) -> float {
+        music_volume_ = SDL_clamp(volume, 0.0F, 1.0F);
+        if (current_music_ != nullptr && current_music_->stream != nullptr) {
+            SDL_SetAudioStreamGain(current_music_->stream, music_volume_);
+        }
+        return music_volume_;
+    }
+
+    void Engine::setOnMusicEnded(std::function<void()> callback) {
+        on_music_ended_ = std::move(callback);
+    }
+
+    void Engine::onMusicDeleted(const Music* music) {
+        if (music == nullptr) { return; }
+        if (current_music_ == music) {
+            stopMusic();
+            current_music_ = nullptr;
+        }
+    }
+
+    // --- Sound ---
+
+    auto Engine::playSound(Sound* sound, const int loop, const int group) -> int {
+        if (sound == nullptr) { return -1; }
+
+        int channel = 0;
+        while (channel < MAX_SIMULTANEOUS_CHANNELS && channels_[channel].state != ChannelState::FREE) { channel++; }
+        if (channel == MAX_SIMULTANEOUS_CHANNELS) {
+            // No hay canal libre, reemplazamos el primero
+            channel = 0;
+        }
+
+        return playSoundOnChannel(sound, channel, loop, group);
+    }
+
+    auto Engine::playSoundOnChannel(Sound* sound, const int channel, const int loop, const int group) -> int {
+        if (sound == nullptr) { return -1; }
+        if (channel < 0 || channel >= MAX_SIMULTANEOUS_CHANNELS) { return -1; }
+
+        stopChannel(channel);
+
+        channels_[channel].sound = sound;
+        channels_[channel].times = loop;
+        channels_[channel].pos = 0;
+        channels_[channel].group = group;
+        channels_[channel].state = ChannelState::PLAYING;
+        channels_[channel].stream = SDL_CreateAudioStream(&channels_[channel].sound->spec, &audio_spec_);
+
+        if (channels_[channel].stream == nullptr) {
+            std::fprintf(stderr, "Ja::Engine::playSoundOnChannel: Failed to create audio stream!\n");
+            channels_[channel].state = ChannelState::FREE;
+            return -1;
+        }
+
+        SDL_PutAudioStreamData(channels_[channel].stream, channels_[channel].sound->buffer.get(), channels_[channel].sound->length);
+        SDL_SetAudioStreamGain(channels_[channel].stream, sound_volume_[group]);
+        SDL_BindAudioStream(sdl_audio_device_, channels_[channel].stream);
+
+        return channel;
+    }
+
+    void Engine::setChannelSpeed(const int channel, const float ratio) {
+        if (channel < 0 || channel >= MAX_SIMULTANEOUS_CHANNELS) { return; }
+        if (channels_[channel].stream == nullptr) { return; }
+        SDL_SetAudioStreamFrequencyRatio(channels_[channel].stream, ratio);
+    }
+
+    void Engine::pauseChannel(const int channel) {
+        forEachTargetChannel(channel, [](Channel& ch) {
+            if (ch.state == ChannelState::PLAYING) {
+                ch.state = ChannelState::PAUSED;
+                SDL_UnbindAudioStream(ch.stream);
+            }
+        });
+    }
+
+    void Engine::resumeChannel(const int channel) {
+        const SDL_AudioDeviceID DEVICE = sdl_audio_device_;
+        forEachTargetChannel(channel, [DEVICE](Channel& ch) {
+            if (ch.state == ChannelState::PAUSED) {
+                ch.state = ChannelState::PLAYING;
+                SDL_BindAudioStream(DEVICE, ch.stream);
+            }
+        });
+    }
+
+    void Engine::stopChannel(const int channel) {
+        forEachTargetChannel(channel, [this](Channel& ch) {
+            if (ch.state != ChannelState::FREE) {
+                if (ch.stream != nullptr) { SDL_DestroyAudioStream(ch.stream); }
+                ch.stream = nullptr;
+                ch.state = ChannelState::FREE;
+                ch.pos = 0;
+                ch.sound = nullptr;
+                if (ch.has_effect) {
+                    ch.has_effect = false;
+                    if (effect_channels_active_ > 0) { --effect_channels_active_; }
+                }
+            }
+        });
+    }
+
+    auto Engine::setSoundVolume(float volume, const int group) -> float {
+        const float V = SDL_clamp(volume, 0.0F, 1.0F);
+
+        if (group == -1) {
+            std::ranges::fill(sound_volume_, V);
+        } else if (group >= 0 && group < MAX_GROUPS) {
+            sound_volume_[group] = V;
+        } else {
+            return V;
+        }
+
+        for (auto& ch : channels_) {
+            if ((ch.state == ChannelState::PLAYING) || (ch.state == ChannelState::PAUSED)) {
+                if (group == -1 || ch.group == group) {
+                    if (ch.stream != nullptr) {
+                        SDL_SetAudioStreamGain(ch.stream, sound_volume_[ch.group]);
+                    }
+                }
+            }
+        }
+        return V;
+    }
+
+    void Engine::onSoundDeleted(const Sound* sound) {
+        if (sound == nullptr) { return; }
+        for (int i = 0; i < MAX_SIMULTANEOUS_CHANNELS; ++i) {
+            if (channels_[i].sound == sound) { stopChannel(i); }
+        }
+    }
+
+    auto Engine::playProcessedOnFreeChannel(const std::vector<std::uint8_t>& bytes, const SDL_AudioSpec& spec, const int group) -> int {
+        // El sin de canals con efecte es valida antes de reservar slot —
+        // así evitem crear y destruir un stream solo per descartar el play.
+        if (effect_channels_active_ >= MAX_EFFECT_CHANNELS) { return -1; }
+
+        int channel = 0;
+        while (channel < MAX_SIMULTANEOUS_CHANNELS && channels_[channel].state != ChannelState::FREE) { ++channel; }
+        if (channel == MAX_SIMULTANEOUS_CHANNELS) { channel = 0; }
+
+        stopChannel(channel);
+
+        // El stream es crea contra l'spec del buffer processat (S16, ...)
+        // porque SDL faci el resampling sin a audio_spec_ del device.
+        channels_[channel].stream = SDL_CreateAudioStream(&spec, &audio_spec_);
+        if (channels_[channel].stream == nullptr) {
+            std::fprintf(stderr, "Ja::Engine::playProcessedOnFreeChannel: Failed to create audio stream!\n");
+            return -1;
+        }
+
+        channels_[channel].sound = nullptr;  // El buffer no es propietat de sin Ja::Sound.
+        channels_[channel].times = 0;
+        channels_[channel].pos = 0;
+        const int CLAMPED_GROUP = (group >= 0 && group < MAX_GROUPS) ? group : 0;
+        channels_[channel].group = CLAMPED_GROUP;
+        channels_[channel].state = ChannelState::PLAYING;
+        channels_[channel].has_effect = true;
+        ++effect_channels_active_;
+
+        SDL_PutAudioStreamData(channels_[channel].stream, bytes.data(), static_cast<int>(bytes.size()));
+        SDL_SetAudioStreamGain(channels_[channel].stream, sound_volume_[CLAMPED_GROUP]);
+        SDL_BindAudioStream(sdl_audio_device_, channels_[channel].stream);
+
+        return channel;
+    }
+
+    auto Engine::playSoundWithEcho(const Sound* sound, const EchoParams& params, const int group) -> int {
+        if (sound == nullptr) { return -1; }
+        auto processed = AudioEffects::applyEcho(*sound, params);
+        if (!processed) { return -1; }
+        return playProcessedOnFreeChannel(processed->bytes, processed->spec, group);
+    }
+
+    auto Engine::playSoundWithReverb(const Sound* sound, const ReverbParams& params, const int group) -> int {
+        if (sound == nullptr) { return -1; }
+        auto processed = AudioEffects::applyReverb(*sound, params);
+        if (!processed) { return -1; }
+        return playProcessedOnFreeChannel(processed->bytes, processed->spec, group);
+    }
+
+    // --- Factories y destructors (permanents) ---
+
+    auto loadMusic(const Uint8* buffer, Uint32 length) -> Music* {
+        if (buffer == nullptr || length == 0) { return nullptr; }
+
+        // Allocem el Music primer per aprofitar el seu `std::vector<Uint8>`
+        // como a propietari del OGG comprimit. stb_vorbis guarda un punter
+        // persistent al buffer; como que ací no el resize'jem, el .data() es
+        // estable durante tot el cicle de vida del music.
+        auto music = std::make_unique<Music>();
+        music->ogg_data.assign(buffer, buffer + length);
+
+        int vorbis_error = 0;
+        music->vorbis = stb_vorbis_open_memory(music->ogg_data.data(),
+            static_cast<int>(length),
+            &vorbis_error,
+            nullptr);
+        if (music->vorbis == nullptr) {
+            std::fprintf(stderr, "Ja::loadMusic: stb_vorbis_open_memory failed (error %d)\n", vorbis_error);
+            return nullptr;
+        }
+
+        const stb_vorbis_info INFO = stb_vorbis_get_info(music->vorbis);
+        music->spec.channels = static_cast<int>(INFO.channels);
+        music->spec.freq = static_cast<int>(INFO.sample_rate);
+        music->spec.format = SDL_AUDIO_S16;
+        // Pre-cálculo de la duración en ms a partir del header. stb_vorbis ya
+        // ha decodificat la informació necessària a `stb_vorbis_open_memory`;
+        // esta consulta no descodifica àudio, solo llig el comptador
+        // de samples. Si el sample_rate fos 0 (header malmès) deixem
+        // duration_ms a 0.
+        if (INFO.sample_rate > 0) {
+            const auto SAMPLES = stb_vorbis_stream_length_in_samples(music->vorbis);
+            music->duration_ms = static_cast<int>((static_cast<std::uint64_t>(SAMPLES) * 1000ULL) / INFO.sample_rate);
+        }
+        music->state = MusicState::STOPPED;
+
+        return music.release();
+    }
+
+    // Overload con filename. Resource::Cache l'usa per registrar el path dins
+    // del propi Ja::Music (camp `filename`); la capa Audio l'usa per recuperar
+    // el nom después d'un playMusic(Ja::Music*, ...) — veure PATCH-02.
+    auto loadMusic(const Uint8* buffer, Uint32 length, const char* filename) -> Music* {
+        Music* music = loadMusic(buffer, length);
+        if (music != nullptr && filename != nullptr) { music->filename = filename; }
+        return music;
+    }
+
+    void deleteMusic(Music* music) {
+        if (music == nullptr) { return; }
+        // Notifiquem el motor actiu porque pari la pista si es la current_music.
+        // Si no hay motor (shutdown-order invertit), passem: los recursos
+        // propis del Music es lliberen igualment a sota.
+        if (Engine* eng = Engine::active()) { eng->onMusicDeleted(music); }
+
+        if (music->stream != nullptr) { SDL_DestroyAudioStream(music->stream); }
+        if (music->vorbis != nullptr) { stb_vorbis_close(music->vorbis); }
+        delete music;
+    }
+
+    auto loadSound(std::uint8_t* buffer, std::uint32_t size) -> Sound* {
+        auto sound = std::make_unique<Sound>();
+        Uint8* raw = nullptr;
+        if (!SDL_LoadWAV_IO(SDL_IOFromMem(buffer, size), true, &sound->spec, &raw, &sound->length)) {
+            std::fprintf(stderr, "Ja::loadSound: Failed to load WAV from memory: %s\n", SDL_GetError());
+            return nullptr;
+        }
+        sound->buffer.reset(raw);  // adopta el SDL_malloc'd buffer
+        return sound.release();
+    }
+
+    void deleteSound(Sound* sound) {
+        if (sound == nullptr) { return; }
+        if (Engine* eng = Engine::active()) { eng->onSoundDeleted(sound); }
+        // buffer es destrueix automàticament via RAII (SdlFreeDeleter).
+        delete sound;
+    }
+
+}  // namespace Ja
+
+// --- stb_vorbis macro leak cleanup ---
+// stb_vorbis.c filtra noms curts (L, C, R i PLAYBACK_*) al TU que el compila.
+// Xocarien con parámetros de plantilla d'altres headers si estas definicions
+// s'escapessin. Els netegem al final del TU per tancar la porta.
+// clang-format off
+#undef L
+#undef C
+#undef R
+#undef PLAYBACK_MONO
+#undef PLAYBACK_LEFT
+#undef PLAYBACK_RIGHT
+// clang-format on
diff --git a/source/core/audio/jail_audio.hpp b/source/core/audio/jail_audio.hpp
index 5e09a86..e46c542 100644
--- a/source/core/audio/jail_audio.hpp
+++ b/source/core/audio/jail_audio.hpp
@@ -2,481 +2,257 @@
 
 // --- Includes ---
 #include <SDL3/SDL.h>
-#include <stdint.h>  // Para uint32_t, uint8_t
-#include <stdio.h>   // Para NULL, fseek, printf, fclose, fopen, fread, ftell, FILE, SEEK_END, SEEK_SET
-#include <stdlib.h>  // Para free, malloc
-#include <string.h>  // Para strcpy, strlen
 
-#define STB_VORBIS_HEADER_ONLY
-#include "external/stb_vorbis.h"  // Para stb_vorbis_decode_memory
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
 
-// --- Public Enums ---
-enum JA_Channel_state { JA_CHANNEL_INVALID,
-    JA_CHANNEL_FREE,
-    JA_CHANNEL_PLAYING,
-    JA_CHANNEL_PAUSED,
-    JA_SOUND_DISABLED };
-enum JA_Music_state { JA_MUSIC_INVALID,
-    JA_MUSIC_PLAYING,
-    JA_MUSIC_PAUSED,
-    JA_MUSIC_STOPPED,
-    JA_MUSIC_DISABLED };
+// Forward-declaració del decoder de vorbis. La implementació viu a
+// jail_audio.cpp (únic TU que compila external/stb_vorbis.c). Qualsevol caller
+// solo necessita `stb_vorbis*` per punter — nunca per valor — así que el
+// forward decl n'hay prou i evita arrossegar el .c a tots los TU.
+// NOLINTNEXTLINE(readability-identifier-naming) — nom imposat per l'API de stb_vorbis
+struct stb_vorbis;
 
-// --- Struct Definitions ---
-#define JA_MAX_SIMULTANEOUS_CHANNELS 20
-#define JA_MAX_GROUPS 2
-
-struct JA_Sound_t {
-        SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
-        Uint32 length{0};
-        Uint8* buffer{NULL};
+// Deleter stateless para buffers reservats con `SDL_malloc` / `SDL_LoadWAV*`.
+// Compatible con `std::unique_ptr<Uint8[], SdlFreeDeleter>` — zero size overhead
+// gràcies a EBO, igual que un unique_ptr con default_delete.
+struct SdlFreeDeleter {
+    void operator()(Uint8* p) const noexcept {
+        if (p != nullptr) { SDL_free(p); }
+    }
 };
 
-struct JA_Channel_t {
-        JA_Sound_t* sound{nullptr};
+// Motor de baix nivell d'àudio del projecte jailgames: streaming OGG
+// (stb_vorbis) + N canals d'efectes (SDL3 audio). No depèn d'Options ni de sin
+// singleton del joc; solo de SDL3 i stb_vorbis. La capa superior (Audio) li
+// passa recursos pel punter i fa el bookkeeping d'usuari.
+namespace Ja {
+
+    // --- Public Enums ---
+    enum class ChannelState : std::uint8_t {
+        FREE,
+        PLAYING,
+        PAUSED,
+    };
+
+    enum class MusicState : std::uint8_t {
+        INVALID,  // Music carregat pero nunca play-ejat
+        PLAYING,
+        PAUSED,
+        STOPPED,
+    };
+
+    // --- Constants ---
+    inline constexpr int MAX_SIMULTANEOUS_CHANNELS = 20;
+    inline constexpr int MAX_GROUPS = 2;
+    // Cap superior de canals que poden estar simultàniament reproduint un so
+    // con efecte (eco/reverb). Si está al límit, las noves crides con efecte
+    // cauen al camí sec — l'usuari sent el so igualment, sin la cua.
+    inline constexpr int MAX_EFFECT_CHANNELS = 4;
+
+    // --- Paràmetres d'efectes ---
+    // Els camps los fixa el caller (Audio) llegint sounds.yaml; el motor solo
+    // los passa a AudioEffects::applyEcho/applyReverb. Els defaults són
+    // sensats pero los presets los sobreescriuen.
+    struct EchoParams {
+        float delay_ms{220.0F};  // Temps hasta al primer rebot.
+        float feedback{0.45F};   // Reinjecció (0..0.95).
+        float wet{0.35F};        // Mescla humida (0..1).
+    };
+
+    struct ReverbParams {
+        float room_size{0.7F};  // Tamaño percebuda (0..1).
+        float damping{0.5F};    // Atenuació d'aguts per rebot (0..1).
+        float wet{0.4F};        // Mescla humida (0..1).
+    };
+
+    // Spec de fallback del dispositiu. S'aplica antes que l'Engine s'iniciï i
+    // como a valor inicial de Sound/Music. L'spec real d'ús l'imposa el ctor
+    // d'Engine, alimentat des de Defaults::Audio via Audio.
+    inline constexpr SDL_AudioSpec DEFAULT_SPEC{SDL_AUDIO_S16, 2, 48000};
+
+    // --- Struct Definitions ---
+    struct Sound {
+        SDL_AudioSpec spec{DEFAULT_SPEC};
+        Uint32 length{0};
+        // Buffer descomprimit (PCM) propietat del sound. Reservat per SDL_LoadWAV
+        // via SDL_malloc; el deleter `SdlFreeDeleter` allibera con SDL_free.
+        std::unique_ptr<Uint8[], SdlFreeDeleter> buffer;
+    };
+
+    // L'ordre (punters primer, ints después, enum de 8 bits al final) minimitza
+    // el padding a 64-bit (evita avisos de clang-analyzer-optin.performance.Padding).
+    struct Channel {
+        Sound* sound{nullptr};
+        SDL_AudioStream* stream{nullptr};
         int pos{0};
         int times{0};
         int group{0};
+        ChannelState state{ChannelState::FREE};
+        // Marca si este canal va arrencar con so processat per un efecte.
+        // El motor compta canals actius con efecte per fer complir
+        // MAX_EFFECT_CHANNELS i alliberar el comptador en parar.
+        bool has_effect{false};
+    };
+
+    struct Music {
+        SDL_AudioSpec spec{DEFAULT_SPEC};
+
+        // OGG comprimit en memòria. Propietat nostra; es copia des del buffer
+        // d'entrada una sola vegada en loadMusic i es descomprimix en chunks
+        // per streaming. Como que stb_vorbis guarda un punter persistent al
+        // `.data()` d'este vector, no el podem resize'jar un cop establert
+        // (una reallocation invalidaria el punter que el decoder conserva).
+        std::vector<Uint8> ogg_data;
+        stb_vorbis* vorbis{nullptr};  // handle del decoder, viu tot el cicle del Music
+
+        std::string filename;
+
+        int times{0};  // loops restants (-1 = infinit, 0 = un sol play)
+        // Duración total de la pista en mil·lisegons, mesurada via
+        // `stb_vorbis_stream_length_in_samples / sample_rate` al
+        // `loadMusic`. 0 si el cálculo no es possible (header malmès).
+        // L'usen consumidors que necessiten un timeline pre-calculat —
+        // p. ex. la FSM de sala — sin dependre de callbacks de fi.
+        int duration_ms{0};
         SDL_AudioStream* stream{nullptr};
-        JA_Channel_state state{JA_CHANNEL_FREE};
-};
+        MusicState state{MusicState::INVALID};
+    };
 
-struct JA_Music_t {
-        SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
-        Uint32 length{0};
-        Uint8* buffer{nullptr};
-        char* filename{nullptr};
+    struct FadeState {
+        bool active{false};
+        Uint64 start_time{0};
+        int duration_ms{0};
+        float initial_volume{0.0F};
+    };
 
-        int pos{0};
-        int times{0};
+    struct OutgoingMusic {
         SDL_AudioStream* stream{nullptr};
-        JA_Music_state state{JA_MUSIC_INVALID};
-};
-
-// --- Internal Global State ---
-// Marcado 'inline' (C++17) para asegurar una única instancia.
-
-inline JA_Music_t* current_music{nullptr};
-inline JA_Channel_t channels[JA_MAX_SIMULTANEOUS_CHANNELS];
-
-inline SDL_AudioSpec JA_audioSpec{SDL_AUDIO_S16, 2, 48000};
-inline float JA_musicVolume{1.0F};
-inline float JA_soundVolume[JA_MAX_GROUPS];
-inline bool JA_musicEnabled{true};
-inline bool JA_soundEnabled{true};
-inline SDL_AudioDeviceID sdlAudioDevice{0};
-
-inline bool fading{false};
-inline int fade_start_time{0};
-inline int fade_duration{0};
-inline float fade_initial_volume{0.0F};  // Corregido de 'int' a 'float'
-
-// --- Forward Declarations ---
-inline void JA_StopMusic();
-inline void JA_StopChannel(const int channel);
-inline int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop = 0, const int group = 0);
-
-// --- Core Functions ---
-
-inline void JA_Update() {
-    if (JA_musicEnabled && current_music && current_music->state == JA_MUSIC_PLAYING) {
-        if (fading) {
-            int time = SDL_GetTicks();
-            if (time > (fade_start_time + fade_duration)) {
-                fading = false;
-                JA_StopMusic();
-                return;
-            } else {
-                const int time_passed = time - fade_start_time;
-                const float percent = (float)time_passed / (float)fade_duration;
-                SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume * (1.0 - percent));
-            }
-        }
-
-        if (current_music->times != 0) {
-            if ((Uint32)SDL_GetAudioStreamAvailable(current_music->stream) < (current_music->length / 2)) {
-                SDL_PutAudioStreamData(current_music->stream, current_music->buffer, current_music->length);
-            }
-            if (current_music->times > 0) current_music->times--;
-        } else {
-            if (SDL_GetAudioStreamAvailable(current_music->stream) == 0) JA_StopMusic();
-        }
-    }
-
-    if (JA_soundEnabled) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i)
-            if (channels[i].state == JA_CHANNEL_PLAYING) {
-                if (channels[i].times != 0) {
-                    if ((Uint32)SDL_GetAudioStreamAvailable(channels[i].stream) < (channels[i].sound->length / 2)) {
-                        SDL_PutAudioStreamData(channels[i].stream, channels[i].sound->buffer, channels[i].sound->length);
-                        if (channels[i].times > 0) channels[i].times--;
-                    }
-                } else {
-                    if (SDL_GetAudioStreamAvailable(channels[i].stream) == 0) JA_StopChannel(i);
-                }
-            }
-    }
-}
-
-inline void JA_Init(const int freq, const SDL_AudioFormat format, const int num_channels) {
-#ifdef _DEBUG
-    SDL_SetLogPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_DEBUG);
-#endif
-
-    JA_audioSpec = {format, num_channels, freq};
-    if (sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);  // Corregido: !sdlAudioDevice -> sdlAudioDevice
-    sdlAudioDevice = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &JA_audioSpec);
-    if (sdlAudioDevice == 0) SDL_Log("Failed to initialize SDL audio!");
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i) channels[i].state = JA_CHANNEL_FREE;
-    for (int i = 0; i < JA_MAX_GROUPS; ++i) JA_soundVolume[i] = 0.5F;
-}
-
-inline void JA_Quit() {
-    if (sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);  // Corregido: !sdlAudioDevice -> sdlAudioDevice
-    sdlAudioDevice = 0;
-}
-
-// --- Music Functions ---
-
-inline JA_Music_t* JA_LoadMusic(const Uint8* buffer, Uint32 length) {
-    JA_Music_t* music = new JA_Music_t();
-
-    int chan, samplerate;
-    short* output;
-    music->length = stb_vorbis_decode_memory(buffer, length, &chan, &samplerate, &output) * chan * 2;
-
-    music->spec.channels = chan;
-    music->spec.freq = samplerate;
-    music->spec.format = SDL_AUDIO_S16;
-    music->buffer = static_cast<Uint8*>(SDL_malloc(music->length));
-    SDL_memcpy(music->buffer, output, music->length);
-    free(output);
-    music->pos = 0;
-    music->state = JA_MUSIC_STOPPED;
-
-    return music;
-}
-
-inline JA_Music_t* JA_LoadMusic(const char* filename) {
-    // [RZC 28/08/22] Carreguem primer el arxiu en memòria y después el descomprimim. Es algo més rapid.
-    FILE* f = fopen(filename, "rb");
-    if (!f) return NULL;  // Añadida comprobación de apertura
-    fseek(f, 0, SEEK_END);
-    long fsize = ftell(f);
-    fseek(f, 0, SEEK_SET);
-    auto* buffer = static_cast<Uint8*>(malloc(fsize + 1));
-    if (!buffer) {  // Añadida comprobación de malloc
-        fclose(f);
-        return NULL;
-    }
-    if (fread(buffer, fsize, 1, f) != 1) {
-        fclose(f);
-        free(buffer);
-        return NULL;
-    }
-    fclose(f);
-
-    JA_Music_t* music = JA_LoadMusic(buffer, fsize);
-    if (music) {  // Comprobar que JA_LoadMusic tuvo éxito
-        music->filename = static_cast<char*>(malloc(strlen(filename) + 1));
-        if (music->filename) {
-            strcpy(music->filename, filename);
-        }
-    }
-
-    free(buffer);
-
-    return music;
-}
-
-inline void JA_PlayMusic(JA_Music_t* music, const int loop = -1) {
-    if (!JA_musicEnabled || !music) return;  // Añadida comprobación de music
-
-    JA_StopMusic();
-
-    current_music = music;
-    current_music->pos = 0;
-    current_music->state = JA_MUSIC_PLAYING;
-    current_music->times = loop;
-
-    current_music->stream = SDL_CreateAudioStream(&current_music->spec, &JA_audioSpec);
-    if (!current_music->stream) {  // Comprobar creación de stream
-        SDL_Log("Failed to create audio stream!");
-        current_music->state = JA_MUSIC_STOPPED;
-        return;
-    }
-    if (!SDL_PutAudioStreamData(current_music->stream, current_music->buffer, current_music->length)) printf("[ERROR] SDL_PutAudioStreamData failed!\n");
-    SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
-    if (!SDL_BindAudioStream(sdlAudioDevice, current_music->stream)) printf("[ERROR] SDL_BindAudioStream failed!\n");
-}
-
-inline char* JA_GetMusicFilename(const JA_Music_t* music = nullptr) {
-    if (!music) music = current_music;
-    if (!music) return nullptr;  // Añadida comprobación
-    return music->filename;
-}
-
-inline void JA_PauseMusic() {
-    if (!JA_musicEnabled) return;
-    if (!current_music || current_music->state != JA_MUSIC_PLAYING) return;  // Comprobación mejorada
-
-    current_music->state = JA_MUSIC_PAUSED;
-    SDL_UnbindAudioStream(current_music->stream);
-}
-
-inline void JA_ResumeMusic() {
-    if (!JA_musicEnabled) return;
-    if (!current_music || current_music->state != JA_MUSIC_PAUSED) return;  // Comprobación mejorada
-
-    current_music->state = JA_MUSIC_PLAYING;
-    SDL_BindAudioStream(sdlAudioDevice, current_music->stream);
-}
-
-inline void JA_StopMusic() {
-    if (!current_music || current_music->state == JA_MUSIC_INVALID || current_music->state == JA_MUSIC_STOPPED) return;
-
-    current_music->pos = 0;
-    current_music->state = JA_MUSIC_STOPPED;
-    if (current_music->stream) {
-        SDL_DestroyAudioStream(current_music->stream);
-        current_music->stream = nullptr;
-    }
-    // No liberamos filename aquí, se debería liberar en JA_DeleteMusic
-}
-
-inline void JA_FadeOutMusic(const int milliseconds) {
-    if (!JA_musicEnabled) return;
-    if (current_music == NULL || current_music->state == JA_MUSIC_INVALID) return;
-
-    fading = true;
-    fade_start_time = SDL_GetTicks();
-    fade_duration = milliseconds;
-    fade_initial_volume = JA_musicVolume;
-}
-
-inline JA_Music_state JA_GetMusicState() {
-    if (!JA_musicEnabled) return JA_MUSIC_DISABLED;
-    if (!current_music) return JA_MUSIC_INVALID;
-
-    return current_music->state;
-}
-
-inline void JA_DeleteMusic(JA_Music_t* music) {
-    if (!music) return;
-    if (current_music == music) {
-        JA_StopMusic();
-        current_music = nullptr;
-    }
-    SDL_free(music->buffer);
-    if (music->stream) SDL_DestroyAudioStream(music->stream);
-    free(music->filename);  // filename se libera aquí
-    delete music;
-}
-
-inline float JA_SetMusicVolume(float volume) {
-    JA_musicVolume = SDL_clamp(volume, 0.0F, 1.0F);
-    if (current_music && current_music->stream) {
-        SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
-    }
-    return JA_musicVolume;
-}
-
-inline void JA_SetMusicPosition(float value) {
-    if (!current_music) return;
-    current_music->pos = value * current_music->spec.freq;
-    // Nota: Esta implementación de 'pos' no parece usarse en JA_Update para
-    // el streaming. El streaming siempre parece empezar desde el principio.
-}
-
-inline float JA_GetMusicPosition() {
-    if (!current_music) return 0;
-    return float(current_music->pos) / float(current_music->spec.freq);
-    // Nota: Ver `JA_SetMusicPosition`
-}
-
-inline void JA_EnableMusic(const bool value) {
-    if (!value && current_music && (current_music->state == JA_MUSIC_PLAYING)) JA_StopMusic();
-
-    JA_musicEnabled = value;
-}
-
-// --- Sound Functions ---
-
-inline JA_Sound_t* JA_NewSound(Uint8* buffer, Uint32 length) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    sound->buffer = buffer;
-    sound->length = length;
-    // Nota: spec se queda con los valores por defecto.
-    return sound;
-}
-
-inline JA_Sound_t* JA_LoadSound(uint8_t* buffer, uint32_t size) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    if (!SDL_LoadWAV_IO(SDL_IOFromMem(buffer, size), 1, &sound->spec, &sound->buffer, &sound->length)) {
-        SDL_Log("Failed to load WAV from memory: %s", SDL_GetError());
-        delete sound;
-        return nullptr;
-    }
-    return sound;
-}
-
-inline JA_Sound_t* JA_LoadSound(const char* filename) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    if (!SDL_LoadWAV(filename, &sound->spec, &sound->buffer, &sound->length)) {
-        SDL_Log("Failed to load WAV file: %s", SDL_GetError());
-        delete sound;
-        return nullptr;
-    }
-    return sound;
-}
-
-inline int JA_PlaySound(JA_Sound_t* sound, const int loop = 0, const int group = 0) {
-    if (!JA_soundEnabled || !sound) return -1;
-
-    int channel = 0;
-    while (channel < JA_MAX_SIMULTANEOUS_CHANNELS && channels[channel].state != JA_CHANNEL_FREE) { channel++; }
-    if (channel == JA_MAX_SIMULTANEOUS_CHANNELS) {
-        // No hay canal libre, reemplazamos el primero
-        channel = 0;
-    }
-
-    return JA_PlaySoundOnChannel(sound, channel, loop, group);
-}
-
-inline int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop, const int group) {
-    if (!JA_soundEnabled || !sound) return -1;
-    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return -1;
-
-    JA_StopChannel(channel);  // Detiene y limpia el canal si estaba en uso
-
-    channels[channel].sound = sound;
-    channels[channel].times = loop;
-    channels[channel].pos = 0;
-    channels[channel].group = group;  // Asignar grupo
-    channels[channel].state = JA_CHANNEL_PLAYING;
-    channels[channel].stream = SDL_CreateAudioStream(&channels[channel].sound->spec, &JA_audioSpec);
-
-    if (!channels[channel].stream) {
-        SDL_Log("Failed to create audio stream for sound!");
-        channels[channel].state = JA_CHANNEL_FREE;
-        return -1;
-    }
-
-    SDL_PutAudioStreamData(channels[channel].stream, channels[channel].sound->buffer, channels[channel].sound->length);
-    SDL_SetAudioStreamGain(channels[channel].stream, JA_soundVolume[group]);
-    SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
-
-    return channel;
-}
-
-inline void JA_DeleteSound(JA_Sound_t* sound) {
-    if (!sound) return;
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-        if (channels[i].sound == sound) JA_StopChannel(i);
-    }
-    SDL_free(sound->buffer);
-    delete sound;
-}
-
-inline void JA_PauseChannel(const int channel) {
-    if (!JA_soundEnabled) return;
-
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
-            if (channels[i].state == JA_CHANNEL_PLAYING) {
-                channels[i].state = JA_CHANNEL_PAUSED;
-                SDL_UnbindAudioStream(channels[i].stream);
-            }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state == JA_CHANNEL_PLAYING) {
-            channels[channel].state = JA_CHANNEL_PAUSED;
-            SDL_UnbindAudioStream(channels[channel].stream);
-        }
-    }
-}
-
-inline void JA_ResumeChannel(const int channel) {
-    if (!JA_soundEnabled) return;
-
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
-            if (channels[i].state == JA_CHANNEL_PAUSED) {
-                channels[i].state = JA_CHANNEL_PLAYING;
-                SDL_BindAudioStream(sdlAudioDevice, channels[i].stream);
-            }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state == JA_CHANNEL_PAUSED) {
-            channels[channel].state = JA_CHANNEL_PLAYING;
-            SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
-        }
-    }
-}
-
-inline void JA_StopChannel(const int channel) {
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-            if (channels[i].state != JA_CHANNEL_FREE) {
-                if (channels[i].stream) SDL_DestroyAudioStream(channels[i].stream);
-                channels[i].stream = nullptr;
-                channels[i].state = JA_CHANNEL_FREE;
-                channels[i].pos = 0;
-                channels[i].sound = NULL;
-            }
-        }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state != JA_CHANNEL_FREE) {
-            if (channels[channel].stream) SDL_DestroyAudioStream(channels[channel].stream);
-            channels[channel].stream = nullptr;
-            channels[channel].state = JA_CHANNEL_FREE;
-            channels[channel].pos = 0;
-            channels[channel].sound = NULL;
-        }
-    }
-}
-
-inline JA_Channel_state JA_GetChannelState(const int channel) {
-    if (!JA_soundEnabled) return JA_SOUND_DISABLED;
-    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return JA_CHANNEL_INVALID;
-
-    return channels[channel].state;
-}
-
-inline float JA_SetSoundVolume(float volume, const int group = -1)  // -1 para todos los grupos
-{
-    const float v = SDL_clamp(volume, 0.0F, 1.0F);
-
-    if (group == -1) {
-        for (int i = 0; i < JA_MAX_GROUPS; ++i) {
-            JA_soundVolume[i] = v;
-        }
-    } else if (group >= 0 && group < JA_MAX_GROUPS) {
-        JA_soundVolume[group] = v;
-    } else {
-        return v;  // Grupo inválido
-    }
-
-    // Aplicar volumen a canales activos
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-        if ((channels[i].state == JA_CHANNEL_PLAYING) || (channels[i].state == JA_CHANNEL_PAUSED)) {
-            if (group == -1 || channels[i].group == group) {
-                if (channels[i].stream) {
-                    SDL_SetAudioStreamGain(channels[i].stream, JA_soundVolume[channels[i].group]);
-                }
-            }
-        }
-    }
-    return v;
-}
-
-inline void JA_EnableSound(const bool value) {
-    if (!value) {
-        JA_StopChannel(-1);  // Detener todos los canales
-    }
-    JA_soundEnabled = value;
-}
-
-inline float JA_SetVolume(float volume) {
-    float v = JA_SetMusicVolume(volume);
-    JA_SetSoundVolume(v, -1);  // Aplicar a todos los grupos de sonido
-    return v;
-}
\ No newline at end of file
+        // Referència al Music original porque updateOutgoingFade puga
+        // continuar descomprimint des de Vorbis sin al stream durante
+        // tota la fosa. Sense això, solo tenim el pre-fill puntual i
+        // SDL drena el stream més ràpid del previst cuando hay sounds
+        // bound a la misma device (~2x), buidant-lo a meitat del
+        // fade i sentint-se como un tall sec.
+        Music* music{nullptr};
+        FadeState fade;
+    };
+
+    // --- Engine ---
+    // Encapsula tot l'estat que antes vivia como a globals inline. Un sol Engine
+    // viu per procés (enforceat via assert al ctor contra `active_`). El ctor
+    // obre el device SDL; el dtor el tanca (RAII). Els deleters
+    // `Ja::deleteMusic`/`Ja::deleteSound` accedeixen al motor actiu via
+    // `Engine::active()` per parar canals antes d'alliberar.
+    class Engine {
+       public:
+        Engine(int freq, SDL_AudioFormat format, int num_channels);
+        ~Engine();
+        Engine(const Engine&) = delete;
+        auto operator=(const Engine&) -> Engine& = delete;
+        Engine(Engine&&) = delete;
+        auto operator=(Engine&&) -> Engine& = delete;
+
+        // Retorna el motor actiu o nullptr si sin ha estat construït. L'usen
+        // los deleters de recursos porque no los arriba sin referència directa.
+        [[nodiscard]] static auto active() noexcept -> Engine*;
+
+        void update();
+
+        // --- Música ---
+        void playMusic(Music* music, int loop = -1);
+        void pauseMusic();
+        void resumeMusic();
+        void stopMusic();
+        void fadeOutMusic(int milliseconds);
+        void crossfadeMusic(Music* music, int crossfade_ms, int loop = -1);
+        [[nodiscard]] auto getMusicState() const -> MusicState;
+        auto setMusicVolume(float volume) -> float;
+        // Multiplicador de velocitat de reproducció de la música actual
+        // via `SDL_SetAudioStreamFrequencyRatio`. 1.0 = normal, 2.0 =
+        // doble velocitat. Cal saber que también puja el to (efecte
+        // "chipmunk") — es el comportament arcade clàssic dels comptes
+        // enrere. Cada `playMusic` crea un stream nuevo con ratio 1.0,
+        // así que un canvi de track reseteja la velocitat
+        // implícitament. No-op si no hay música activa.
+        void setMusicSpeed(float ratio);
+        // Registra un callback que es disparà cuando la música actual acabi de
+        // drenar naturalment (times == 0 + stream buit). Es crida DESPRÉS de
+        // stopMusic, así que el callback pot invocar playMusic sin córrer.
+        // S'executa al mismo thread que Engine::update (render loop); no fer
+        // operacions blocants.
+        void setOnMusicEnded(std::function<void()> callback);
+        // Notifica al motor que un Music s'está destruint: si es el current_music
+        // s'atura antes que los seus recursos (stream/vorbis) deixin de ser vàlids.
+        void onMusicDeleted(const Music* music);
+
+        // --- So ---
+        auto playSound(Sound* sound, int loop = 0, int group = 0) -> int;
+        auto playSoundOnChannel(Sound* sound, int channel, int loop = 0, int group = 0) -> int;
+        // Ajusta la velocitat de reproducció d'un canal actiu via
+        // `SDL_SetAudioStreamFrequencyRatio`. 1.0 = normal. Igual que a
+        // `setMusicSpeed`, puja/baixa el to junt con la velocitat
+        // (efecte "chipmunk"); para SFX curts arcade es el que volem.
+        // No-op si el canal no está actiu. Cridar-lo just después de
+        // `playSound`/`playSoundOnChannel` porque el ratio cobreixi
+        // tota la reproducció.
+        void setChannelSpeed(int channel, float ratio);
+        // Reproducció con so processat per un efecte. Retorna el canal
+        // assignat o -1 si no queden slots d'efecte (MAX_EFFECT_CHANNELS).
+        // El sound original solo s'usa per consultar el spec/buffer; el
+        // canal manipula el buffer ya processat (no reapunta a `sound`).
+        auto playSoundWithEcho(const Sound* sound, const EchoParams& params, int group = 0) -> int;
+        auto playSoundWithReverb(const Sound* sound, const ReverbParams& params, int group = 0) -> int;
+        void pauseChannel(int channel);
+        void resumeChannel(int channel);
+        void stopChannel(int channel);
+        auto setSoundVolume(float volume, int group = -1) -> float;
+        // Notifica al motor que un Sound s'está destruint: los canals que el
+        // referenciïn es paren antes d'alliberar el buffer.
+        void onSoundDeleted(const Sound* sound);
+
+       private:
+        void stealCurrentIntoOutgoing(int duration_ms);
+        void updateOutgoingFade();
+        void updateIncomingFade();
+        void updateCurrentMusic();
+        void updateSoundChannels();
+        // Empenta un buffer ya processat (S16) a un canal lliure y el deixa
+        // sonar sin bucle. Camí comú dels dos overloads playSoundWith*.
+        // Retorna el canal o -1 si no queden slots.
+        auto playProcessedOnFreeChannel(const std::vector<std::uint8_t>& bytes, const SDL_AudioSpec& spec, int group) -> int;
+
+        template <typename Fn>
+        void forEachTargetChannel(int channel, Fn&& fn);
+
+        Music* current_music_{nullptr};
+        Channel channels_[MAX_SIMULTANEOUS_CHANNELS]{};
+        SDL_AudioSpec audio_spec_{DEFAULT_SPEC};
+        float music_volume_{1.0F};
+        float sound_volume_[MAX_GROUPS]{};
+        SDL_AudioDeviceID sdl_audio_device_{0};
+        OutgoingMusic outgoing_music_;
+        FadeState incoming_fade_;
+        std::function<void()> on_music_ended_;
+        // Comptador derivat de Channel::has_effect — evita haver-lo de
+        // recalcular cada vegada que algú demana un play con efecte.
+        int effect_channels_active_{0};
+
+        // NOLINTNEXTLINE(readability-identifier-naming) — convenció projecte: private static con sufix _
+        static Engine* active_;
+    };
+
+    // --- Factories y destructors (permanents) ---
+    // No depenen de l'estat del motor: loadMusic/loadSound solo construeixen
+    // objectes, deleteMusic/deleteSound consulten Engine::active() per parar
+    // canals antes d'alliberar (si el motor aún viu).
+    [[nodiscard]] auto loadMusic(const Uint8* buffer, Uint32 length) -> Music*;
+    [[nodiscard]] auto loadMusic(const Uint8* buffer, Uint32 length, const char* filename) -> Music*;
+    void deleteMusic(Music* music);
+    [[nodiscard]] auto loadSound(std::uint8_t* buffer, std::uint32_t size) -> Sound*;
+    void deleteSound(Sound* sound);
+
+}  // namespace Ja
diff --git a/source/core/audio/sound_effects_config.cpp b/source/core/audio/sound_effects_config.cpp
new file mode 100644
index 0000000..b8da792
--- /dev/null
+++ b/source/core/audio/sound_effects_config.cpp
@@ -0,0 +1,80 @@
+#include "core/audio/sound_effects_config.hpp"
+
+#include <string>
+
+#include <iostream>
+
+#include "core/resources/resource_helper.hpp"
+#include "external/fkyaml_node.hpp"
+
+namespace {
+
+    // Lector de camp con fallback: deixa el destí intacte si la clau no
+    // existeix (los defaults dels Ja::*Params s'inicialitzen al ctor del
+    // struct, así que el comportament es "preset parcial = preset complet
+    // con defaults per als camps que falten").
+    template <typename T>
+    void readField(const fkyaml::node& node, const char* key, T& dst) {
+        if (node.contains(key)) { dst = node[key].get_value<T>(); }
+    }
+
+}  // namespace
+
+auto SoundEffectsConfig::get() -> SoundEffectsConfig& {
+    static SoundEffectsConfig instance_;
+    return instance_;
+}
+
+void SoundEffectsConfig::load(const std::string& file_path) {
+    auto bytes = Resource::Helper::loadFile(file_path);
+    if (bytes.empty()) {
+        std::cerr << "[SoundEffectsConfig] no se ha podido abrir " << file_path
+                  << " — sin presets de efecto disponibles\n";
+        return;
+    }
+
+    try {
+        const auto* begin = reinterpret_cast<const char*>(bytes.data());
+        const auto* end = begin + bytes.size();
+        auto yaml = fkyaml::node::deserialize(begin, end);
+
+        if (yaml.contains("echo") && yaml["echo"].is_mapping()) {
+            for (auto it = yaml["echo"].begin(); it != yaml["echo"].end(); ++it) {
+                const auto NAME = it.key().get_value<std::string>();
+                const auto& node = it.value();
+                Ja::EchoParams params{};
+                readField(node, "delay_ms", params.delay_ms);
+                readField(node, "feedback", params.feedback);
+                readField(node, "wet", params.wet);
+                echoes_[NAME] = params;
+            }
+        }
+
+        if (yaml.contains("reverb") && yaml["reverb"].is_mapping()) {
+            for (auto it = yaml["reverb"].begin(); it != yaml["reverb"].end(); ++it) {
+                const auto NAME = it.key().get_value<std::string>();
+                const auto& node = it.value();
+                Ja::ReverbParams params{};
+                readField(node, "room_size", params.room_size);
+                readField(node, "damping", params.damping);
+                readField(node, "wet", params.wet);
+                reverbs_[NAME] = params;
+            }
+        }
+
+        std::cout << "[SoundEffectsConfig] " << echoes_.size() << " preset(s) de echo y "
+                  << reverbs_.size() << " de reverb desde " << file_path << "\n";
+    } catch (const std::exception& e) {
+        std::cerr << "[SoundEffectsConfig] error parseando " << file_path << ": " << e.what() << "\n";
+    }
+}
+
+auto SoundEffectsConfig::findEcho(const std::string& name) const -> const Ja::EchoParams* {
+    const auto IT = echoes_.find(name);
+    return (IT == echoes_.end()) ? nullptr : &IT->second;
+}
+
+auto SoundEffectsConfig::findReverb(const std::string& name) const -> const Ja::ReverbParams* {
+    const auto IT = reverbs_.find(name);
+    return (IT == reverbs_.end()) ? nullptr : &IT->second;
+}
diff --git a/source/core/audio/sound_effects_config.hpp b/source/core/audio/sound_effects_config.hpp
new file mode 100644
index 0000000..0b46015
--- /dev/null
+++ b/source/core/audio/sound_effects_config.hpp
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <string>
+#include <unordered_map>
+
+#include "core/audio/jail_audio.hpp"  // Para Ja::EchoParams / Ja::ReverbParams
+
+// Catàleg de presets d'efectes carregat des de data/config/sounds.yaml. La capa
+// Audio (playSoundWithEcho/playSoundWithReverb) hi accedeix per nom: si el
+// preset no existeix, el so es reprodueix sec con un avís a stderr.
+//
+// Patró Meyers idèntic a UiConfig/Locale: un sol load() a l'arrencada, sense
+// hot-reload. Si el archivo no existeix, el catàleg queda buit (sin preset
+// disponible) i tots los playSoundWith* es comporten como playSound dry.
+class SoundEffectsConfig {
+   public:
+    static auto get() -> SoundEffectsConfig&;
+
+    SoundEffectsConfig(const SoundEffectsConfig&) = delete;
+    SoundEffectsConfig(SoundEffectsConfig&&) = delete;
+    auto operator=(const SoundEffectsConfig&) -> SoundEffectsConfig& = delete;
+    auto operator=(SoundEffectsConfig&&) -> SoundEffectsConfig& = delete;
+
+    void load(const std::string& file_path);
+
+    // Retorna nullptr si el preset no existeix.
+    [[nodiscard]] auto findEcho(const std::string& name) const -> const Ja::EchoParams*;
+    [[nodiscard]] auto findReverb(const std::string& name) const -> const Ja::ReverbParams*;
+
+   private:
+    SoundEffectsConfig() = default;
+    ~SoundEffectsConfig() = default;
+
+    std::unordered_map<std::string, Ja::EchoParams> echoes_;
+    std::unordered_map<std::string, Ja::ReverbParams> reverbs_;
+};
diff --git a/source/core/defaults.hpp b/source/core/defaults.hpp
index 687bd08..d4894e4 100644
--- a/source/core/defaults.hpp
+++ b/source/core/defaults.hpp
@@ -280,16 +280,23 @@ namespace Rendering {
 constexpr int VSYNC_DEFAULT = 1;  // 0=disabled, 1=enabled
 }  // namespace Rendering
 
-// Audio (sistema de so i música)
+// Audio (sistema de sonido y música) — usado por Audio::Config en init()
 namespace Audio {
-constexpr float VOLUME = 1.0F;  // Volumen maestro (0.0 a 1.0)
-constexpr bool ENABLED = true;  // Audio habilitado por defecto
+constexpr bool ENABLED = true;        // Audio habilitado por defecto
+constexpr float VOLUME = 1.0F;        // Volumen maestro (0..1)
+constexpr bool MUSIC_ENABLED = true;  // Música habilitada
+constexpr float MUSIC_VOLUME = 0.8F;  // Volumen música (0..1)
+constexpr bool SOUND_ENABLED = true;  // Efectos habilitados
+constexpr float SOUND_VOLUME = 1.0F;  // Volumen efectos (0..1)
+constexpr float VOLUME_STEP = 0.05F;  // Paso UI (5%)
+constexpr int FREQUENCY = 48000;      // Frecuencia de muestreo (Hz)
+constexpr int CROSSFADE_MS = 1500;    // Crossfade por defecto entre pistas (ms)
+constexpr SDL_AudioFormat FORMAT = SDL_AUDIO_S16;  // PCM 16-bit signed nativo
+constexpr int CHANNELS = 2;           // Estéreo
 }  // namespace Audio
 
 // Música (pistas de fondo)
 namespace Music {
-constexpr float VOLUME = 0.8F;                    // Volumen música
-constexpr bool ENABLED = true;                    // Música habilitada
 constexpr const char* GAME_TRACK = "game.ogg";    // Pista de juego
 constexpr const char* TITLE_TRACK = "title.ogg";  // Pista de titulo
 constexpr int FADE_DURATION_MS = 1000;            // Fade out duration
@@ -297,8 +304,6 @@ constexpr int FADE_DURATION_MS = 1000;            // Fade out duration
 
 // Efectes de so (sons puntuals)
 namespace Sound {
-constexpr float VOLUME = 1.0F;                                               // Volumen efectos
-constexpr bool ENABLED = true;                                               // Sonidos habilitados
 constexpr const char* CONTINUE = "effects/continue.wav";                     // Cuenta atras
 constexpr const char* EXPLOSION = "effects/explosion.wav";                   // Explosión
 constexpr const char* EXPLOSION2 = "effects/explosion2.wav";                 // Explosión alternativa
diff --git a/source/core/system/director.cpp b/source/core/system/director.cpp
index 4096a13..81edc12 100644
--- a/source/core/system/director.cpp
+++ b/source/core/system/director.cpp
@@ -9,7 +9,7 @@
 
 #include "scene_context.hpp"
 #include "core/audio/audio.hpp"
-#include "core/audio/audio_cache.hpp"
+#include "core/audio/audio_adapter.hpp"
 #include "core/defaults.hpp"
 #include "core/input/input.hpp"
 #include "core/input/mouse.hpp"
@@ -224,17 +224,23 @@ auto Director::run() -> int {
         Mouse::forceHide();
     }
 
-    // Inicialitzar sistema de audio
-    Audio::init();
-    Audio::get()->setMusicVolume(1.0);
-    Audio::get()->setSoundVolume(0.4);
+    // Inicializar sistema de audio (config inyectada desde Defaults)
+    const Audio::Config AUDIO_CONFIG{
+        .enabled = Defaults::Audio::ENABLED,
+        .volume = Defaults::Audio::VOLUME,
+        .music_enabled = Defaults::Audio::MUSIC_ENABLED,
+        .music_volume = Defaults::Audio::MUSIC_VOLUME,
+        .sound_enabled = Defaults::Audio::SOUND_ENABLED,
+        .sound_volume = Defaults::Audio::SOUND_VOLUME,
+    };
+    Audio::init(AUDIO_CONFIG);
+    Audio::get()->applySettings(AUDIO_CONFIG);  // Aplicar volúmenes iniciales al motor
 
-    // Precachejar música per evitar lag al començar
-    AudioCache::getMusic("title.ogg");
-    AudioCache::getMusic("game.ogg");
+    // Precachear música para evitar lag al empezar
+    AudioResource::getMusic("title.ogg");
+    AudioResource::getMusic("game.ogg");
     if (Options::console) {
-        std::cout << "Música precachejada: "
-                  << AudioCache::getMusicCacheSize() << " archivos\n";
+        std::cout << "Música precacheada\n";
     }
 
     // Crear context de escenes
diff --git a/source/external/stb_vorbis.h b/source/external/stb_vorbis.c
similarity index 98%
rename from source/external/stb_vorbis.h
rename to source/external/stb_vorbis.c
index 49df433..7e5daa3 100644
--- a/source/external/stb_vorbis.h
+++ b/source/external/stb_vorbis.c
@@ -1,4 +1,4 @@
-// Ogg Vorbis audio decoder - v1.20 - public domain
+// Ogg Vorbis audio decoder - v1.22 - public domain
 // http://nothings.org/stb_vorbis/
 //
 // Original version written by Sean Barrett in 2007.
@@ -29,12 +29,15 @@
 //    Bernhard Wodo      Evan Balster        github:alxprd
 //    Tom Beaumont       Ingo Leitgeb        Nicolas Guillemot
 //    Phillip Bennefall  Rohit               Thiago Goulart
-//    github:manxorist   saga musix          github:infatum
+//    github:manxorist   Saga Musix          github:infatum
 //    Timur Gagiev       Maxwell Koo         Peter Waller
 //    github:audinowho   Dougall Johnson     David Reid
 //    github:Clownacy    Pedro J. Estebanez  Remi Verschelde
+//    AnthoFoxo          github:morlat       Gabriel Ravier
 //
 // Partial history:
+//    1.22    - 2021-07-11 - various small fixes
+//    1.21    - 2021-07-02 - fix bug for files with no comments
 //    1.20    - 2020-07-11 - several small fixes
 //    1.19    - 2020-02-05 - warnings
 //    1.18    - 2020-02-02 - fix seek bugs; parse header comments; misc warnings etc.
@@ -220,6 +223,12 @@ extern int stb_vorbis_decode_frame_pushdata(
 // channel. In other words, (*output)[0][0] contains the first sample from
 // the first channel, and (*output)[1][0] contains the first sample from
 // the second channel.
+//
+// *output points into stb_vorbis's internal output buffer storage; these
+// buffers are owned by stb_vorbis and application code should not free
+// them or modify their contents. They are transient and will be overwritten
+// once you ask for more data to get decoded, so be sure to grab any data
+// you need before then.
 
 extern void stb_vorbis_flush_pushdata(stb_vorbis *f);
 // inform stb_vorbis that your next datablock will not be contiguous with
@@ -579,7 +588,7 @@ enum STBVorbisError
    #if defined(_MSC_VER) || defined(__MINGW32__)
       #include <malloc.h>
    #endif
-   #if defined(__linux__) || defined(__linux) || defined(__EMSCRIPTEN__) || defined(__NEWLIB__)
+   #if defined(__linux__) || defined(__linux) || defined(__sun__) || defined(__EMSCRIPTEN__) || defined(__NEWLIB__)
       #include <alloca.h>
    #endif
 #else // STB_VORBIS_NO_CRT
@@ -646,6 +655,12 @@ typedef   signed int    int32;
 
 typedef float codetype;
 
+#ifdef _MSC_VER
+#define STBV_NOTUSED(v)  (void)(v)
+#else
+#define STBV_NOTUSED(v)  (void)sizeof(v)
+#endif
+
 // @NOTE
 //
 // Some arrays below are tagged "//varies", which means it's actually
@@ -1046,7 +1061,7 @@ static float float32_unpack(uint32 x)
    uint32 sign = x & 0x80000000;
    uint32 exp = (x & 0x7fe00000) >> 21;
    double res = sign ? -(double)mantissa : (double)mantissa;
-   return (float) ldexp((float)res, exp-788);
+   return (float) ldexp((float)res, (int)exp-788);
 }
 
 
@@ -1077,6 +1092,7 @@ static int compute_codewords(Codebook *c, uint8 *len, int n, uint32 *values)
    // find the first entry
    for (k=0; k < n; ++k) if (len[k] < NO_CODE) break;
    if (k == n) { assert(c->sorted_entries == 0); return TRUE; }
+   assert(len[k] < 32); // no error return required, code reading lens checks this
    // add to the list
    add_entry(c, 0, k, m++, len[k], values);
    // add all available leaves
@@ -1090,6 +1106,7 @@ static int compute_codewords(Codebook *c, uint8 *len, int n, uint32 *values)
       uint32 res;
       int z = len[i], y;
       if (z == NO_CODE) continue;
+      assert(z < 32); // no error return required, code reading lens checks this
       // find lowest available leaf (should always be earliest,
       // which is what the specification calls for)
       // note that this property, and the fact we can never have
@@ -1099,12 +1116,10 @@ static int compute_codewords(Codebook *c, uint8 *len, int n, uint32 *values)
       while (z > 0 && !available[z]) --z;
       if (z == 0) { return FALSE; }
       res = available[z];
-      assert(z >= 0 && z < 32);
       available[z] = 0;
       add_entry(c, bit_reverse(res), i, m++, len[i], values);
       // propagate availability up the tree
       if (z != len[i]) {
-         assert(len[i] >= 0 && len[i] < 32);
          for (y=len[i]; y > z; --y) {
             assert(available[y] == 0);
             available[y] = res + (1 << (32-y));
@@ -2577,34 +2592,33 @@ static void imdct_step3_inner_s_loop_ld654(int n, float *e, int i_off, float *A,
 
    while (z > base) {
       float k00,k11;
+      float l00,l11;
 
-      k00   = z[-0] - z[-8];
-      k11   = z[-1] - z[-9];
-      z[-0] = z[-0] + z[-8];
-      z[-1] = z[-1] + z[-9];
-      z[-8] =  k00;
-      z[-9] =  k11 ;
+      k00    = z[-0] - z[ -8];
+      k11    = z[-1] - z[ -9];
+      l00    = z[-2] - z[-10];
+      l11    = z[-3] - z[-11];
+      z[ -0] = z[-0] + z[ -8];
+      z[ -1] = z[-1] + z[ -9];
+      z[ -2] = z[-2] + z[-10];
+      z[ -3] = z[-3] + z[-11];
+      z[ -8] = k00;
+      z[ -9] = k11;
+      z[-10] = (l00+l11) * A2;
+      z[-11] = (l11-l00) * A2;
 
-      k00    = z[ -2] - z[-10];
-      k11    = z[ -3] - z[-11];
-      z[ -2] = z[ -2] + z[-10];
-      z[ -3] = z[ -3] + z[-11];
-      z[-10] = (k00+k11) * A2;
-      z[-11] = (k11-k00) * A2;
-
-      k00    = z[-12] - z[ -4];  // reverse to avoid a unary negation
+      k00    = z[ -4] - z[-12];
       k11    = z[ -5] - z[-13];
+      l00    = z[ -6] - z[-14];
+      l11    = z[ -7] - z[-15];
       z[ -4] = z[ -4] + z[-12];
       z[ -5] = z[ -5] + z[-13];
-      z[-12] = k11;
-      z[-13] = k00;
-
-      k00    = z[-14] - z[ -6];  // reverse to avoid a unary negation
-      k11    = z[ -7] - z[-15];
       z[ -6] = z[ -6] + z[-14];
       z[ -7] = z[ -7] + z[-15];
-      z[-14] = (k00+k11) * A2;
-      z[-15] = (k00-k11) * A2;
+      z[-12] = k11;
+      z[-13] = -k00;
+      z[-14] = (l11-l00) * A2;
+      z[-15] = (l00+l11) * -A2;
 
       iter_54(z);
       iter_54(z-8);
@@ -3069,6 +3083,7 @@ static int do_floor(vorb *f, Mapping *map, int i, int n, float *target, YTYPE *f
       for (q=1; q < g->values; ++q) {
          j = g->sorted_order[q];
          #ifndef STB_VORBIS_NO_DEFER_FLOOR
+         STBV_NOTUSED(step2_flag);
          if (finalY[j] >= 0)
          #else
          if (step2_flag[j])
@@ -3171,6 +3186,7 @@ static int vorbis_decode_packet_rest(vorb *f, int *len, Mode *m, int left_start,
 
 // WINDOWING
 
+   STBV_NOTUSED(left_end);
    n = f->blocksize[m->blockflag];
    map = &f->mapping[m->mapping];
 
@@ -3368,7 +3384,7 @@ static int vorbis_decode_packet_rest(vorb *f, int *len, Mode *m, int left_start,
       // this isn't to spec, but spec would require us to read ahead
       // and decode the size of all current frames--could be done,
       // but presumably it's not a commonly used feature
-      f->current_loc = -n2; // start of first frame is positioned for discard
+      f->current_loc = 0u - n2; // start of first frame is positioned for discard (NB this is an intentional unsigned overflow/wrap-around)
       // we might have to discard samples "from" the next frame too,
       // if we're lapping a large block then a small at the start?
       f->discard_samples_deferred = n - right_end;
@@ -3642,9 +3658,11 @@ static int start_decoder(vorb *f)
    f->vendor[len] = (char)'\0';
    //user comments
    f->comment_list_length = get32_packet(f);
-   if (f->comment_list_length > 0) {
-        f->comment_list = (char**)setup_malloc(f, sizeof(char*) * (f->comment_list_length));
-        if (f->comment_list == NULL)                     return error(f, VORBIS_outofmem);
+   f->comment_list = NULL;
+   if (f->comment_list_length > 0)
+   {
+      f->comment_list = (char**) setup_malloc(f, sizeof(char*) * (f->comment_list_length));
+      if (f->comment_list == NULL)                  return error(f, VORBIS_outofmem);
    }
 
    for(i=0; i < f->comment_list_length; ++i) {
@@ -3867,8 +3885,7 @@ static int start_decoder(vorb *f)
                unsigned int div=1;
                for (k=0; k < c->dimensions; ++k) {
                   int off = (z / div) % c->lookup_values;
-                  float val = mults[off];
-                  val = mults[off]*c->delta_value + c->minimum_value + last;
+                  float val = mults[off]*c->delta_value + c->minimum_value + last;
                   c->multiplicands[j*c->dimensions + k] = val;
                   if (c->sequence_p)
                      last = val;
@@ -3951,7 +3968,7 @@ static int start_decoder(vorb *f)
                if (g->class_masterbooks[j] >= f->codebook_count) return error(f, VORBIS_invalid_setup);
             }
             for (k=0; k < 1 << g->class_subclasses[j]; ++k) {
-               g->subclass_books[j][k] = get_bits(f,8)-1;
+               g->subclass_books[j][k] = (int16)get_bits(f,8)-1;
                if (g->subclass_books[j][k] >= f->codebook_count) return error(f, VORBIS_invalid_setup);
             }
          }
@@ -4509,6 +4526,7 @@ stb_vorbis *stb_vorbis_open_pushdata(
          *error = VORBIS_need_more_data;
       else
          *error = p.error;
+      vorbis_deinit(&p);
       return NULL;
    }
    f = vorbis_alloc(&p);
@@ -4566,7 +4584,7 @@ static uint32 vorbis_find_page(stb_vorbis *f, uint32 *end, uint32 *last)
                header[i] = get8(f);
             if (f->eof) return 0;
             if (header[4] != 0) goto invalid;
-            goal = header[22] + (header[23] << 8) + (header[24]<<16) + (header[25]<<24);
+            goal = header[22] + (header[23] << 8) + (header[24]<<16) + ((uint32)header[25]<<24);
             for (i=22; i < 26; ++i)
                header[i] = 0;
             crc = 0;
@@ -4970,7 +4988,7 @@ unsigned int stb_vorbis_stream_length_in_samples(stb_vorbis *f)
             // set. whoops!
             break;
          }
-         previous_safe = last_page_loc+1;
+         //previous_safe = last_page_loc+1; // NOTE: not used after this point, but note for debugging
          last_page_loc = stb_vorbis_get_file_offset(f);
       }
 
@@ -5081,7 +5099,10 @@ stb_vorbis * stb_vorbis_open_filename(const char *filename, int *error, const st
 stb_vorbis * stb_vorbis_open_memory(const unsigned char *data, int len, int *error, const stb_vorbis_alloc *alloc)
 {
    stb_vorbis *f, p;
-   if (data == NULL) return NULL;
+   if (!data) {
+      if (error) *error = VORBIS_unexpected_eof;
+      return NULL;
+   }
    vorbis_init(&p, alloc);
    p.stream = (uint8 *) data;
    p.stream_end = (uint8 *) data + len;
@@ -5156,11 +5177,11 @@ static void copy_samples(short *dest, float *src, int len)
 
 static void compute_samples(int mask, short *output, int num_c, float **data, int d_offset, int len)
 {
-   #define BUFFER_SIZE  32
-   float buffer[BUFFER_SIZE];
-   int i,j,o,n = BUFFER_SIZE;
+   #define STB_BUFFER_SIZE  32
+   float buffer[STB_BUFFER_SIZE];
+   int i,j,o,n = STB_BUFFER_SIZE;
    check_endianness();
-   for (o = 0; o < len; o += BUFFER_SIZE) {
+   for (o = 0; o < len; o += STB_BUFFER_SIZE) {
       memset(buffer, 0, sizeof(buffer));
       if (o + n > len) n = len - o;
       for (j=0; j < num_c; ++j) {
@@ -5177,16 +5198,17 @@ static void compute_samples(int mask, short *output, int num_c, float **data, in
          output[o+i] = v;
       }
    }
+   #undef STB_BUFFER_SIZE
 }
 
 static void compute_stereo_samples(short *output, int num_c, float **data, int d_offset, int len)
 {
-   #define BUFFER_SIZE  32
-   float buffer[BUFFER_SIZE];
-   int i,j,o,n = BUFFER_SIZE >> 1;
+   #define STB_BUFFER_SIZE  32
+   float buffer[STB_BUFFER_SIZE];
+   int i,j,o,n = STB_BUFFER_SIZE >> 1;
    // o is the offset in the source data
    check_endianness();
-   for (o = 0; o < len; o += BUFFER_SIZE >> 1) {
+   for (o = 0; o < len; o += STB_BUFFER_SIZE >> 1) {
       // o2 is the offset in the output data
       int o2 = o << 1;
       memset(buffer, 0, sizeof(buffer));
@@ -5216,6 +5238,7 @@ static void compute_stereo_samples(short *output, int num_c, float **data, int d
          output[o2+i] = v;
       }
    }
+   #undef STB_BUFFER_SIZE
 }
 
 static void convert_samples_short(int buf_c, short **buffer, int b_offset, int data_c, float **data, int d_offset, int samples)
@@ -5288,8 +5311,6 @@ int stb_vorbis_get_samples_short_interleaved(stb_vorbis *f, int channels, short
    float **outputs;
    int len = num_shorts / channels;
    int n=0;
-   int z = f->channels;
-   if (z > channels) z = channels;
    while (n < len) {
       int k = f->channel_buffer_end - f->channel_buffer_start;
       if (n+k >= len) k = len - n;
@@ -5308,8 +5329,6 @@ int stb_vorbis_get_samples_short(stb_vorbis *f, int channels, short **buffer, in
 {
    float **outputs;
    int n=0;
-   int z = f->channels;
-   if (z > channels) z = channels;
    while (n < len) {
       int k = f->channel_buffer_end - f->channel_buffer_start;
       if (n+k >= len) k = len - n;
diff --git a/source/external/stb_vorbis_impl.cpp b/source/external/stb_vorbis_impl.cpp
new file mode 100644
index 0000000..7adf65f
--- /dev/null
+++ b/source/external/stb_vorbis_impl.cpp
@@ -0,0 +1,13 @@
+// Unitat de compilació aïllada per a la implementació de stb_vorbis.
+// Viu dins de source/external/ perquè el `.clang-tidy` d'aquesta carpeta
+// desactiva tots els checks (com fa per stb_image_write_impl.cpp) i el
+// pre-commit hook ja filtra aquesta ruta de clang-format / clang-tidy.
+// Així els fals positius de clang-analyzer-* dins de codi C de tercers
+// no afecten el nostre codi, que continua tenint tots els checks actius.
+//
+// jail_audio.cpp defineix STB_VORBIS_HEADER_ONLY abans d'incloure el .c,
+// així només en veu les declaracions; les definicions les aporta aquest
+// TU i l'enllaçador les resol.
+
+// NOLINTNEXTLINE(bugprone-suspicious-include)
+#include "external/stb_vorbis.c"
diff --git a/source/game/options.cpp b/source/game/options.cpp
index 21e627d..4a23a62 100644
--- a/source/game/options.cpp
+++ b/source/game/options.cpp
@@ -210,10 +210,10 @@ void init() {
     // Audio
     audio.enabled = Defaults::Audio::ENABLED;
     audio.volume = Defaults::Audio::VOLUME;
-    audio.music.enabled = Defaults::Music::ENABLED;
-    audio.music.volume = Defaults::Music::VOLUME;
-    audio.sound.enabled = Defaults::Sound::ENABLED;
-    audio.sound.volume = Defaults::Sound::VOLUME;
+    audio.music.enabled = Defaults::Audio::MUSIC_ENABLED;
+    audio.music.volume = Defaults::Audio::MUSIC_VOLUME;
+    audio.sound.enabled = Defaults::Audio::SOUND_ENABLED;
+    audio.sound.volume = Defaults::Audio::SOUND_VOLUME;
 
     // Version
     version = std::string(Project::VERSION);
@@ -409,16 +409,16 @@ static void loadAudioConfigFromYaml(const fkyaml::node& yaml) {
                 try {
                     audio.music.enabled = mus["enabled"].get_value<bool>();
                 } catch (...) {
-                    audio.music.enabled = Defaults::Music::ENABLED;
+                    audio.music.enabled = Defaults::Audio::MUSIC_ENABLED;
                 }
             }
 
             if (mus.contains("volume")) {
                 try {
                     auto val = mus["volume"].get_value<float>();
-                    audio.music.volume = (val >= 0.0F && val <= 1.0F) ? val : Defaults::Music::VOLUME;
+                    audio.music.volume = (val >= 0.0F && val <= 1.0F) ? val : Defaults::Audio::MUSIC_VOLUME;
                 } catch (...) {
-                    audio.music.volume = Defaults::Music::VOLUME;
+                    audio.music.volume = Defaults::Audio::MUSIC_VOLUME;
                 }
             }
         }
@@ -430,16 +430,16 @@ static void loadAudioConfigFromYaml(const fkyaml::node& yaml) {
                 try {
                     audio.sound.enabled = snd["enabled"].get_value<bool>();
                 } catch (...) {
-                    audio.sound.enabled = Defaults::Sound::ENABLED;
+                    audio.sound.enabled = Defaults::Audio::SOUND_ENABLED;
                 }
             }
 
             if (snd.contains("volume")) {
                 try {
                     auto val = snd["volume"].get_value<float>();
-                    audio.sound.volume = (val >= 0.0F && val <= 1.0F) ? val : Defaults::Sound::VOLUME;
+                    audio.sound.volume = (val >= 0.0F && val <= 1.0F) ? val : Defaults::Audio::SOUND_VOLUME;
                 } catch (...) {
-                    audio.sound.volume = Defaults::Sound::VOLUME;
+                    audio.sound.volume = Defaults::Audio::SOUND_VOLUME;
                 }
             }
         }
diff --git a/source/game/scenes/title_scene.cpp b/source/game/scenes/title_scene.cpp
index a62be14..00101c0 100644
--- a/source/game/scenes/title_scene.cpp
+++ b/source/game/scenes/title_scene.cpp
@@ -94,7 +94,7 @@ TitleScene::TitleScene(SDLManager& sdl, SceneContext& context)
     inicialitzar_titol();
 
     // Iniciar música de título si no está sonant
-    if (Audio::get()->getMusicState() != Audio::MusicState::PLAYING) {
+    if (Audio::getMusicState() != Audio::MusicState::PLAYING) {
         Audio::get()->playMusic("title.ogg");
     }
 }
diff --git a/source/game/stage_system/stage_manager.cpp b/source/game/stage_system/stage_manager.cpp
index 6a729e4..d6bfa69 100644
--- a/source/game/stage_system/stage_manager.cpp
+++ b/source/game/stage_system/stage_manager.cpp
@@ -88,7 +88,7 @@ void StageManager::canviar_estat(EstatStage nou_estat) {
 
         // [NOU] Iniciar música al entrar en LEVEL_START (después de INIT_HUD)
         // Solo si no está sonant ya (per evitar reset en loops posteriors)
-        if (Audio::get()->getMusicState() != Audio::MusicState::PLAYING) {
+        if (Audio::getMusicState() != Audio::MusicState::PLAYING) {
             Audio::get()->playMusic("game.ogg");
         }
     }