Render Rhythma sessions as layered ambient audio

Introduce a dedicated session renderer that moves the project beyond a single modulated tone and toward the approved ambient design. The new renderer keeps the existing engine intact while adding a layered path for drone, breath pulse, shimmer, and session envelope so later UI work can present a more immersive session without rewriting the engine again.

Constraint: Task 2 must stay scoped to the engine and its targeted tests
Constraint: Session rendering must always include a breath pulse layer regardless of profile modulation type
Rejected: Reusing the legacy single-layer modulation path as the session renderer | not deep enough for the approved redesign
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Preserve duration validation and the attack/release envelope when expanding the renderer in later tasks
Tested: python -m py_compile rhythma_engine.py tests/test_rhythma_layered_audio.py tests/test_rhythma_regression.py
Tested: PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -c "import pytest; raise SystemExit(pytest.main(['tests/test_rhythma_layered_audio.py','tests/test_rhythma_regression.py','-q','-p','no:cacheprovider']))"
Not-tested: Integration with app.py and session profiles in the live UI; deferred to later tasks

rhythma_engine.py

@@ -215,6 +215,110 @@ class RhythmaModulationEngine:
         )
         return carrier * mod_env
 
+    def _normalize_audio(self, audio):
+        max_amp = np.max(np.abs(audio))
+        if max_amp <= 0:
+            return audio
+        return 0.9 * audio / max_amp
+
+    def _render_drone_layer(self, t, tone_center, density, config):
+        drone = np.zeros_like(t)
+        density = float(np.clip(density, 0.0, 1.0))
+        harmonic_count = 2 if density < 0.5 else 3
+        for index, harmonic_amp in enumerate(config["harmonics"][:harmonic_count], start=1):
+            harmonic_freq = tone_center * index
+            if harmonic_freq < self.sample_rate / 2:
+                drone += harmonic_amp * np.sin(2 * np.pi * harmonic_freq * t)
+
+        max_amp = np.max(np.abs(drone))
+        if max_amp > 0:
+            drone = drone / max_amp
+        return drone * (0.75 + 0.25 * density)
+
+    def _render_breath_layer(self, t, tone_center, breath_rate, pattern):
+        breath_rate = max(0.02, float(breath_rate))
+        breath_freq = max(40.0, tone_center * 0.5)
+        carrier = np.sin(2 * np.pi * breath_freq * t)
+        pattern_config = self.rhythm_configs.get(pattern, self.config)
+        breath_env = 0.5 * (
+            signal.square(
+                2 * np.pi * breath_rate * t,
+                duty=pattern_config["pulse_width"],
+            )
+            + 1.0
+        )
+
+        return carrier * breath_env
+
+    def _render_shimmer_layer(self, t, tone_center, brightness, shimmer):
+        brightness = float(np.clip(brightness, 0.0, 1.0))
+        shimmer = float(np.clip(shimmer, 0.0, 1.0))
+        shimmer_layer = np.zeros_like(t)
+        harmonic_levels = [
+            (2.0, 0.35 + 0.25 * brightness),
+            (3.0, 0.2 + 0.2 * shimmer),
+            (4.0, 0.1 + 0.15 * brightness),
+        ]
+        for index, (multiplier, amplitude) in enumerate(harmonic_levels, start=1):
+            harmonic_freq = tone_center * multiplier
+            if harmonic_freq < self.sample_rate / 2:
+                shimmer_layer += amplitude * np.sin(
+                    2 * np.pi * harmonic_freq * t + (index * np.pi / 7)
+                )
+
+        max_amp = np.max(np.abs(shimmer_layer))
+        if max_amp > 0:
+            shimmer_layer = shimmer_layer / max_amp
+
+        shimmer_motion = 0.6 + 0.4 * np.sin(
+            2 * np.pi * max(0.1, 1.5 + shimmer * 3.0) * t
+        )
+        return shimmer_layer * shimmer_motion * (0.2 + 0.8 * brightness)
+
+    def _build_session_envelope(self, sample_count):
+        if sample_count <= 1:
+            return np.ones(sample_count)
+
+        attack_count = max(1, int(sample_count * 0.08))
+        release_count = max(1, int(sample_count * 0.12))
+        if attack_count + release_count >= sample_count:
+            attack_count = max(1, sample_count // 2)
+            release_count = sample_count - attack_count
+        sustain_count = sample_count - attack_count - release_count
+
+        attack = np.linspace(0.0, 1.0, attack_count, endpoint=False)
+        sustain = np.ones(sustain_count)
+        release = np.linspace(1.0, 0.0, release_count, endpoint=True)
+        return np.concatenate([attack, sustain, release])
+
+    def render_session(self, profile, duration):
+        sample_count = int(self.sample_rate * duration)
+        if duration <= 0 or sample_count < 1:
+            raise ValueError("duration must produce at least one sample")
+
+        tone_center = float(profile.get("tone_center", self.base_freq))
+        pattern = profile.get("pattern", self.rhythm_pattern)
+        config = self.rhythm_configs.get(pattern, self.config)
+        t = np.linspace(0, duration, sample_count, endpoint=False)
+
+        drone = self._render_drone_layer(t, tone_center, profile.get("density", 0.5), config)
+        pulse = self._render_breath_layer(
+            t,
+            tone_center,
+            profile.get("breath_rate", config["mod_freq"] / 8),
+            pattern,
+        )
+        shimmer = self._render_shimmer_layer(
+            t,
+            tone_center,
+            profile.get("brightness", 0.25),
+            profile.get("shimmer", 0.1),
+        )
+
+        combined = (0.62 * drone) + (0.25 * pulse) + (0.13 * shimmer)
+        combined = combined * self._build_session_envelope(len(t))
+        return self._normalize_audio(combined)
+
     def generate_modulated_wave(self, duration):
         t, base_carrier = self._generate_base_wave(duration)
 
@@ -227,10 +331,7 @@ class RhythmaModulationEngine:
         else:
             modulated = base_carrier
 
-        max_amp = np.max(np.abs(modulated))
-        if max_amp <= 0:
-            return modulated
-        return 0.9 * modulated / max_amp
+        return self._normalize_audio(modulated)
 
     def save_audio(self, duration, file_path=None):
         if not SOUNDFILE_AVAILABLE:

tests/test_rhythma_layered_audio.py

@@ -0,0 +1,78 @@
+import numpy as np
+import pytest
+
+from rhythma_engine import RhythmaModulationEngine
+
+
+def test_render_session_returns_normalized_layered_audio():
+    engine = RhythmaModulationEngine()
+    profile = {
+        "tone_center": 396.0,
+        "pattern": "calm",
+        "modulation_type": "sine",
+        "brightness": 0.25,
+        "density": 0.45,
+        "shimmer": 0.12,
+        "breath_rate": 0.08,
+    }
+
+    audio = engine.render_session(profile, duration=4)
+
+    assert len(audio) == engine.sample_rate * 4
+    assert np.max(np.abs(audio)) <= 0.9 + 1e-9
+    assert np.max(np.abs(audio[:400])) < np.max(np.abs(audio[2000:2400]))
+    assert np.max(np.abs(audio[-400:])) < np.max(np.abs(audio[2000:2400]))
+
+
+def test_render_session_is_not_identical_to_single_layer_base_wave():
+    engine = RhythmaModulationEngine()
+    profile = {
+        "tone_center": 639.0,
+        "pattern": "focused",
+        "modulation_type": "sine",
+        "brightness": 0.4,
+        "density": 0.35,
+        "shimmer": 0.18,
+        "breath_rate": 0.12,
+    }
+
+    session_audio = engine.render_session(profile, duration=3)
+    legacy_audio = engine.generate_modulated_wave(3)
+
+    assert not np.allclose(session_audio[:2000], legacy_audio[:2000])
+
+
+def test_render_session_keeps_breath_layer_pulse_shaped():
+    engine = RhythmaModulationEngine()
+    pulse_profile = {
+        "tone_center": 528.0,
+        "pattern": "relaxed",
+        "modulation_type": "pulse",
+        "brightness": 0.3,
+        "density": 0.4,
+        "shimmer": 0.15,
+        "breath_rate": 0.1,
+    }
+    chirp_profile = dict(pulse_profile, modulation_type="chirp")
+
+    pulse_audio = engine.render_session(pulse_profile, duration=2)
+    chirp_audio = engine.render_session(chirp_profile, duration=2)
+
+    assert np.allclose(pulse_audio, chirp_audio)
+
+
+@pytest.mark.parametrize("duration", [0, -1, 0.5 / RhythmaModulationEngine.SAMPLE_RATE])
+def test_render_session_rejects_invalid_duration(duration):
+    engine = RhythmaModulationEngine()
+    profile = {
+        "tone_center": 528.0,
+        "pattern": "calm",
+        "modulation_type": "sine",
+        "brightness": 0.2,
+        "density": 0.3,
+        "shimmer": 0.1,
+        "breath_rate": 0.08,
+    }
+
+    with pytest.raises(ValueError, match="duration must produce at least one sample"):
+        engine.render_session(profile, duration=duration)

tests/test_rhythma_regression.py

@@ -24,10 +24,19 @@ def test_analyze_input_defaults_to_neutral_when_no_text_is_provided():
     assert result["error"] is None
 
 
-def test_generate_modulated_wave_has_expected_length_and_headroom():
-    engine = RhythmaModulationEngine(emotional_state="stressed")
-
-    wave = engine.generate_modulated_wave(0.1)
+def test_render_session_has_expected_length_and_headroom():
+    engine = RhythmaModulationEngine(emotional_state="stressed", rhythm_pattern="calm")
+    profile = {
+        "tone_center": engine.base_freq,
+        "pattern": "calm",
+        "modulation_type": "sine",
+        "brightness": 0.2,
+        "density": 0.4,
+        "shimmer": 0.1,
+        "breath_rate": 0.08,
+    }
+
+    wave = engine.render_session(profile, 0.1)
 
     assert len(wave) == 4410
     assert np.max(np.abs(wave)) <= 0.9 + 1e-9