Implement all 12 SFX pipeline improvements from the guide

Waveform fixes:
- Fix broken SAW_TOOTH, TRIANGLE, PULSE in Instrument.generate()
  using correct phase-based math (matching Oscillator.emit())
- Replace per-sample Random allocation in Oscillator noise with
  persistent Random instance

Envelope improvements:
- Switch ADSR from linear to quadratic curves for natural sound
  (x^2 attack, inverse-square decay/release)
- Add minimum 2ms release (88 samples) to prevent clicks
- Add safety fade-out at buffer boundaries in SoundManager

New effects:
- Add Tremolo class (amplitude modulation LFO) in Effect.kt
- Add configurable dutyCycle field to Instrument for PULSE wave
- Wire dutyCycle through Oscillator and InstrumentPlayer

Mixing improvements:
- Replace all hard clipping with tanh-based soft saturation
- Add softClip() to SoundManager companion, used in SoundManager,
  JavaSoundManager, and MixerGateway
- Add harmonics normalization inside Harmonizer.generate()
- Make master volume a configurable instance var on SoundManager

DC offset handling:
- Subtract analytical DC offset from PULSE waves
- Add single-pole high-pass DC blocker for NOISE waves

Documentation:
- Fix Harmonizer KDoc (index 0 = fundamental, not 2nd harmonic)

Tests updated for new quadratic envelope curves, harmonizer
normalization, and click prevention behavior.

https://claude.ai/code/session_01XDAnX2yoseGsbSS2YGCirn

Author: claude

tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/sound/Effect.kt

@@ -59,3 +59,30 @@ class Vibrato(
         return frequency + vibrato
     }
 }
+
+/**
+ * Tremolo effect — amplitude modulation using a low-frequency oscillator (LFO).
+ *
+ * Unlike [Modulation] which modulates frequency, tremolo modulates the amplitude
+ * of the signal. Typical LFO rates are 2–10 Hz.
+ *
+ * @param frequency LFO rate in Hz
+ * @param depth Modulation depth: 0.0 = no effect, 1.0 = full tremolo
+ */
+@Serializable
+class Tremolo(
+    var frequency: Frequency = 0f,
+    var depth: Percent = 0f,
+) {
+    var active: Boolean = false
+
+    fun apply(
+        time: Seconds,
+        sample: Float,
+    ): Float {
+        if (!active || depth == 0f) return sample
+        // LFO oscillates between (1-depth) and 1.0
+        val lfo = (1.0f - depth) + depth * ((sin(TWO_PI * frequency * time) + 1.0f) * 0.5f)
+        return sample * lfo
+    }
+}

tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/sound/Envelop.kt

@@ -2,6 +2,7 @@ package com.github.minigdx.tiny.sound
 
 import com.github.minigdx.tiny.Percent
 import com.github.minigdx.tiny.Sample
+import kotlin.math.max
 
 class Envelop(
     internal val attack0: () -> Sample,
@@ -13,6 +14,10 @@ class Envelop(
      * Return the multiplier to apply to a sample value regarding the progression of the sound.
      * The [noteOn] phase will apply the [attack] then the [decay] then the [sustain]
      * and keep the [sustain] until the [noteOff].
+     *
+     * Uses quadratic curves for more natural-sounding envelopes:
+     * - Attack uses x^2 (slow start, fast finish)
+     * - Decay uses inverse-square (fast drop, slow tail toward sustain)
      */
     fun noteOn(progress: Sample): Percent {
         val attack = attack0.invoke()
@@ -22,21 +27,23 @@ class Envelop(
         return when {
             progress < 0 -> 0.0f
             progress <= attack -> {
-                // Attack phase: 0.0 to 1.0 over attack samples
+                // Attack phase: 0.0 to 1.0 with quadratic curve (slow start, fast finish)
                 if (attack == 0) {
                     1.0f
                 } else {
-                    progress.toFloat() / attack.toFloat()
+                    val linear = progress.toFloat() / attack.toFloat()
+                    linear * linear
                 }
             }
             progress <= attack + decay -> {
-                // Decay phase: 1.0 to sustain over decay samples
+                // Decay phase: 1.0 to sustain with inverse-square curve (fast drop, slow tail)
                 if (decay == 0) {
                     sustain
                 } else {
                     val decayProgress = progress - attack
-                    val decayAmount = 1.0f - sustain
-                    1.0f - (decayAmount * decayProgress.toFloat() / decay.toFloat())
+                    val linear = decayProgress.toFloat() / decay.toFloat()
+                    val remaining = 1.0f - linear
+                    sustain + (1.0f - sustain) * remaining * remaining
                 }
             }
             else -> {
@@ -49,24 +56,33 @@ class Envelop(
     /**
      * Return the multiplier to apply to a sample value regarding the progression of the sound.
      * The [noteOff] will apply the [attack] then the [decay] then right away the [release].
+     *
+     * Enforces a minimum release duration of ~2ms (88 samples at 44100 Hz)
+     * to prevent audible clicks from abrupt note endings.
+     *
+     * Uses quadratic curve (fast drop, slow tail) for natural release.
      */
     fun noteOff(progress: Sample): Percent {
         val sustain = sustain0.invoke()
-        val release = release0.invoke()
+        val release = max(MIN_RELEASE_SAMPLES, release0.invoke())
 
         return when {
+            progress < 0 -> 0.0f
             progress <= release -> {
-                // Release phase: sustain to 0.0 over release samples
-                if (release == 0 || progress < 0) {
-                    0.0f
-                } else {
-                    sustain * (1.0f - progress.toFloat() / release.toFloat())
-                }
+                // Release phase: sustain to 0.0 with quadratic curve (fast drop, slow tail)
+                val linear = progress.toFloat() / release.toFloat()
+                val remaining = 1.0f - linear
+                sustain * remaining * remaining
             }
             else -> {
                 // After release: silence
                 0.0f
             }
         }
     }
+
+    companion object {
+        // ~2ms at 44100 Hz - minimum release to prevent clicks
+        const val MIN_RELEASE_SAMPLES = 88
+    }
 }

tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/sound/Harmonizer.kt

@@ -9,12 +9,16 @@ import com.github.minigdx.tiny.lua.Note
  * with the fundamental frequency of a note. This creates richer, more complex sounds
  * than simple sine waves.
  *
- * Each harmonic is a multiple of the fundamental frequency (2x, 3x, 4x, etc.) and
+ * Each harmonic is a multiple of the fundamental frequency (1x, 2x, 3x, etc.) and
  * has its own amplitude weight defined in the harmonics array.
  *
- * @param harmonics Array of relative amplitudes for each harmonic. Index 0 represents
- *                  the first harmonic (2x fundamental), index 1 represents the second
- *                  harmonic (3x fundamental), etc. Values typically range from 0.0 to 1.0.
+ * The output is normalized so that the sum of harmonics never exceeds [-1, 1],
+ * preventing clipping in downstream stages.
+ *
+ * @param harmonics0 Array of relative amplitudes for each harmonic. Index 0 represents
+ *                   the fundamental (1x frequency), index 1 represents the 2nd harmonic
+ *                   (2x frequency), index 2 represents the 3rd harmonic (3x frequency), etc.
+ *                   Values typically range from 0.0 to 1.0.
  */
 class Harmonizer(
     val harmonics0: () -> FloatArray,
@@ -24,11 +28,13 @@ class Harmonizer(
      * Each harmonic frequency is calculated as a multiple of the fundamental frequency,
      * and the generator function is called to produce the actual waveform value for each frequency.
      *
+     * The result is normalized by the total harmonic amplitude to prevent exceeding [-1, 1].
+     *
      * @param note The musical note that provides the fundamental frequency
      * @param sample The current sample number (used for time-based calculations)
-     * @param generator A function that generates waveform values given a frequency and harmonic number.
-     *                  Takes (frequency, harmonicNumber) and returns the waveform sample value.
-     * @return The combined sample value of the fundamental frequency and all its harmonics
+     * @param generator A function that generates waveform values given a frequency and sample index.
+     *                  Takes (frequency, sampleIndex) and returns the waveform sample value.
+     * @return The combined and normalized sample value
      */
     fun generate(
         note: Note,
@@ -39,16 +45,18 @@ class Harmonizer(
 
         val harmonics = harmonics0.invoke()
         var sampleValue = 0f
+        var totalAmplitude = 0f
         harmonics.forEachIndexed { index, relativeAmplitude ->
-            // Harmonic numbers start at 1 (fundamental is implied to be 1x)
-            // So index 0 = 2nd harmonic (2x), index 1 = 3rd harmonic (3x), etc.
             val harmonicNumber = index + 1
             val harmonicFreq = fundamentalFreq * harmonicNumber
             val value = generator.invoke(harmonicFreq, sample)
 
-            // Weight the harmonic contribution by its relative amplitude
             sampleValue += relativeAmplitude * value
+            totalAmplitude += relativeAmplitude
         }
-        return sampleValue
+
+        // Normalize to prevent exceeding [-1, 1]
+        val normFactor = if (totalAmplitude > 1.0f) 1.0f / totalAmplitude else 1.0f
+        return sampleValue * normFactor
     }
 }

tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/sound/Instrument.kt

@@ -2,7 +2,6 @@ package com.github.minigdx.tiny.sound
 
 import com.github.minigdx.tiny.Percent
 import com.github.minigdx.tiny.Seconds
-import com.github.minigdx.tiny.lua.Note
 import com.github.minigdx.tiny.sound.Instrument.WaveType.NOISE
 import com.github.minigdx.tiny.sound.Instrument.WaveType.PULSE
 import com.github.minigdx.tiny.sound.Instrument.WaveType.SAW_TOOTH
@@ -13,7 +12,6 @@ import com.github.minigdx.tiny.sound.SoundManager.Companion.SAMPLE_RATE
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
 import kotlin.math.PI
-import kotlin.math.abs
 import kotlin.math.exp
 import kotlin.math.max
 import kotlin.math.sin
@@ -61,9 +59,18 @@ class Instrument(
      * Will be applied in the order configured.
      */
     val modulations: List<Modulation> = listOf(
-        Sweep(Note.A5.frequency, 1f),
+        Sweep(440f, 1f),
         Vibrato(0f, 0f),
     ),
+    /**
+     * Duty cycle for the PULSE wave type.
+     * 0.5 = square wave, 0.25 = nasal, 0.125 = thin/reedy.
+     */
+    var dutyCycle: Percent = 0.5f,
+    /**
+     * Tremolo effect (amplitude modulation).
+     */
+    val tremolo: Tremolo = Tremolo(),
 ) {
     enum class WaveType {
         SAW_TOOTH,
@@ -74,7 +81,7 @@ class Instrument(
         SQUARE,
     }
 
-    // Last output generated. Used by the [NOISE] wave type
+    // State for NOISE wave type - low-pass filter
     @Transient
     private var lastOutput: Float = 0.0f
 
@@ -84,6 +91,16 @@ class Instrument(
     @Transient
     private var cachedAlpha: Float = 0.0f
 
+    @Transient
+    private val random: Random = Random(42)
+
+    // DC blocker state for NOISE
+    @Transient
+    private var dcBlockerPrev: Float = 0f
+
+    @Transient
+    private var dcBlockerOut: Float = 0f
+
     fun generate(
         freq: Float,
         time: Float,
@@ -92,36 +109,35 @@ class Instrument(
         val harmonicFreq = modulations.filter { it.active }
             .fold(freq) { acc, modulation -> modulation.apply(time, acc) }
 
-        return when (this.wave) {
+        val sample = when (this.wave) {
             TRIANGLE -> {
-                val angle: Float = sin(TWO_PI * harmonicFreq * time)
-                val phase = (angle + 1.0) % 1.0 // Normalize sinValue to the range [0, 1]
-                return (if (phase < 0.5) 4.0 * phase - 1.0 else 3.0 - 4.0 * phase).toFloat()
+                val phase = (harmonicFreq * time) % 1.0f
+                if (phase < 0.5f) {
+                    (4.0f * phase) - 1.0f
+                } else {
+                    3.0f - (4.0f * phase)
+                }
             }
 
             SINE -> sin(TWO_PI * harmonicFreq * time)
+
             SQUARE -> {
                 val value = sin(TWO_PI * harmonicFreq * time)
-                return if (value > 0f) {
-                    1f
-                } else {
-                    -1f
-                }
+                if (value > 0f) 1f else -1f
             }
 
             PULSE -> {
-                val angle = sin(TWO_PI * harmonicFreq * time)
-
-                val t = angle % 1
-                val k = abs(2.0 * ((angle / 128.0) % 1.0) - 1.0)
-                val u = (t + 0.5 * k) % 1.0
-                val ret = abs(4.0 * u - 2.0) - abs(8.0 * t - 4.0)
-                return (ret / 6.0).toFloat()
+                val phase = (harmonicFreq * time) % 1.0f
+                val dc = dutyCycle
+                val raw = if (phase < dc) 1.0f else -1.0f
+                // Remove DC offset for non-50% duty cycles
+                val dcOffset = (2.0f * dc) - 1.0f
+                raw - dcOffset
             }
 
             SAW_TOOTH -> {
-                val angle: Float = sin(TWO_PI * harmonicFreq * time)
-                return (angle * 2f) - 1f
+                val phase = (harmonicFreq * time) % 1.0f
+                (2.0f * phase) - 1.0f
             }
 
             NOISE -> {
@@ -132,18 +148,23 @@ class Instrument(
                         val safeCutoff = max(1f, harmonicFreq)
                         val wc = TWO_PI * safeCutoff / SAMPLE_RATE
                         val x = exp(-wc)
-                        // Cache values
                         cachedAlpha = 1.0f - x
                         lastFrequencyUsed = harmonicFreq
-
                         cachedAlpha
                     }
-                val white = Random.nextFloat() * 2f - 1f
-                val result = alpha * white + (1.0f - alpha) * lastOutput
-                lastOutput = result
-                return result
+                val white = random.nextFloat() * 2f - 1f
+                val filtered = alpha * white + (1.0f - alpha) * lastOutput
+                lastOutput = filtered
+
+                // DC blocker (single-pole high-pass, ~20 Hz cutoff)
+                val dcAlpha = 0.997f
+                dcBlockerOut = dcAlpha * (dcBlockerOut + filtered - dcBlockerPrev)
+                dcBlockerPrev = filtered
+                dcBlockerOut
             }
         }
+
+        return tremolo.apply(time, sample)
     }
 
     companion object {

tiny-engine/src/commonMain/kotlin/com/github/minigdx/tiny/sound/InstrumentPlayer.kt

@@ -39,7 +39,10 @@ class InstrumentPlayer(private val instrument: Instrument) {
 
     private val harmonizer = Harmonizer({ instrument.harmonics })
 
-    private val oscillator = Oscillator({ instrument.wave })
+    private val oscillator = Oscillator(
+        waveType0 = { instrument.wave },
+        dutyCycle0 = { instrument.dutyCycle },
+    )
 
     private val notesOn = mutableSetOf<NoteProgress>()
     private val notesOff = mutableSetOf<NoteProgress>()