docs(02): create phase plan — 3 plans across 3 waves

2026-03-26 11:36:43 +01:00
parent 0e74f94782
commit 08f1a87a54
4 changed files with 1002 additions and 3 deletions
@@ -0,0 +1,324 @@
+---
+phase: 02-audio-synthesis-engine
+plan: 02
+type: execute
+wave: 2
+depends_on: ["02-01"]
+files_modified:
+  - synth/bank.go
+  - synth/mixer.go
+  - synth/bank_test.go
+  - synth/mixer_test.go
+autonomous: true
+requirements: [SYNTH-03]
+
+must_haves:
+  truths:
+    - "OscillatorBank updates all 11 layers from a WindowSnapshot and renders stereo PCM frames"
+    - "Mixer sums 11 layers with fixed 1/11 gain per layer — peak sum never exceeds 1.0"
+    - "Stereo panning uses constant-power pan law producing distinct L/R values for non-center sources"
+    - "Full render pipeline: WindowSnapshot -> OscillatorBank.RenderWindow -> [][2]float64 stereo frames"
+  artifacts:
+    - path: "synth/bank.go"
+      provides: "OscillatorBank with NewBank, RenderWindow methods"
+      contains: "func (b *OscillatorBank) RenderWindow"
+    - path: "synth/mixer.go"
+      provides: "panGains constant-power function and float64-to-int16 conversion"
+      contains: "func PanGains"
+  key_links:
+    - from: "synth/bank.go"
+      to: "synth/layer.go"
+      via: "Bank holds map[TrafficClass]*Layer"
+      pattern: "map\\[classify\\.TrafficClass\\]\\*Layer"
+    - from: "synth/bank.go"
+      to: "synth/config.go"
+      via: "Reads ClassFreqConfigs to initialize layers"
+      pattern: "ClassFreqConfigs"
+    - from: "synth/mixer.go"
+      to: "synth/bank.go"
+      via: "StereoFramesToInt16Bytes converts bank output to encoder-ready bytes"
+      pattern: "StereoFramesToInt16Bytes"
+---
+
+<objective>
+Build the oscillator bank (11 layers driven by WindowSnapshot) and stereo mixer with int16 PCM conversion. This completes SYNTH-03 (mixing without distortion) and prepares the PCM output format needed by the MP3 encoder in Plan 03.
+
+Purpose: The bank is the core synthesis engine that transforms traffic snapshots into stereo audio frames. The mixer ensures no clipping via fixed gain and provides constant-power stereo panning.
+
+Output: `synth/bank.go`, `synth/mixer.go` with tests.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/02-audio-synthesis-engine/02-CONTEXT.md
+@.planning/phases/02-audio-synthesis-engine/02-RESEARCH.md
+@.planning/phases/02-audio-synthesis-engine/02-01-SUMMARY.md
+
+@classify/types.go
+
+<interfaces>
+<!-- From synth/config.go (created in Plan 01) -->
+From synth/config.go:
+```go
+const (
+    SampleRate       = 44100
+    WindowMs         = 500
+    SamplesPerWindow = SampleRate * WindowMs / 1000  // 22050
+    NumLayers        = 11
+    GainPerLayer     = 1.0 / float64(NumLayers)
+    WhisperFloor     = 0.03
+)
+
+type HarmonicDef struct {
+    Ratio     int
+    Amplitude float64
+}
+
+type FreqConfig struct {
+    BaseHz    float64
+    Harmonics []HarmonicDef
+    Pan       float64
+}
+
+var ClassFreqConfigs = map[classify.TrafficClass]FreqConfig{ ... }
+```
+
+From synth/oscillator.go:
+```go
+func NewOscillator(freq float64, sampleRate int) *Oscillator
+func (o *Oscillator) Advance(harmonics []HarmonicDef) float64
+```
+
+From synth/layer.go:
+```go
+func NewLayer(cfg FreqConfig, sampleRate int, tau float64) *Layer
+func (l *Layer) UpdateTarget(count int64, maxCount int64)
+func (l *Layer) AdvanceSample() float64
+func (l *Layer) CurrentAmp() float64
+```
+
+From classify/types.go:
+```go
+func AllClasses() []TrafficClass
+type WindowSnapshot struct {
+    Counts       map[TrafficClass]int64
+    TotalPackets int64
+    WindowIndex  int
+}
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Stereo mixer utilities</name>
+  <files>synth/mixer.go, synth/mixer_test.go</files>
+  <read_first>
+    - synth/config.go (constants: GainPerLayer, SamplesPerWindow, SampleRate)
+    - .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (Pattern 3: constant-power panning, Pattern 4: int16 conversion)
+    - .planning/phases/02-audio-synthesis-engine/02-CONTEXT.md (D-10, D-11, D-12, D-13)
+  </read_first>
+  <behavior>
+    - TestPanGainsCenter: PanGains(0.0) returns gainL ~= 0.707, gainR ~= 0.707 (cos(pi/4), sin(pi/4))
+    - TestPanGainsFullLeft: PanGains(-1.0) returns gainL ~= 1.0, gainR ~= 0.0
+    - TestPanGainsFullRight: PanGains(1.0) returns gainL ~= 0.0, gainR ~= 1.0
+    - TestPanGainsPowerPreserved: For any pan value, gainL^2 + gainR^2 ~= 1.0 (constant power)
+    - TestStereoFramesToInt16Bytes: [][2]float64{{1.0, -1.0}} produces 4 bytes: int16(32767) LE then int16(-32767) LE
+    - TestStereoFramesToInt16BytesZero: [][2]float64{{0.0, 0.0}} produces 4 zero bytes
+    - TestClampPreventsOverflow: float64 value > 1.0 is clamped to 1.0 before int16 conversion (no wrap-around)
+  </behavior>
+  <action>
+**synth/mixer.go** — Constant-power pan law (per D-11) and PCM conversion utilities:
+
+```go
+package synth
+
+import (
+    "encoding/binary"
+    "math"
+)
+
+// PanGains returns left and right channel gains for a pan position p in [-1, 1].
+// Uses constant-power (equal-power) pan law: cos/sin mapping.
+// Per D-11: bass frequencies center, mid spread L/R, higher frequencies wider.
+func PanGains(p float64) (gainL, gainR float64) {
+    angle := (p + 1.0) / 2.0 * math.Pi / 2.0
+    return math.Cos(angle), math.Sin(angle)
+}
+
+// StereoFramesToInt16Bytes converts [][2]float64 stereo frames to interleaved
+// little-endian int16 bytes suitable for go-lame's Write method.
+// Clamps values to [-1.0, 1.0] before conversion.
+// Output format: [L0_lo, L0_hi, R0_lo, R0_hi, L1_lo, L1_hi, R1_lo, R1_hi, ...]
+func StereoFramesToInt16Bytes(frames [][2]float64) []byte {
+    buf := make([]byte, len(frames)*4) // 2 channels * 2 bytes per sample
+    for i, frame := range frames {
+        l := clamp(frame[0])
+        r := clamp(frame[1])
+        binary.LittleEndian.PutUint16(buf[i*4:], uint16(int16(l*32767)))
+        binary.LittleEndian.PutUint16(buf[i*4+2:], uint16(int16(r*32767)))
+    }
+    return buf
+}
+
+func clamp(v float64) float64 {
+    if v > 1.0 {
+        return 1.0
+    }
+    if v < -1.0 {
+        return -1.0
+    }
+    return v
+}
+```
+
+Write tests FIRST (RED), then implementation (GREEN).
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/yoloyolo && go test ./synth/... -run "TestPan|TestStereo|TestClamp" -v -count=1</automated>
+  </verify>
+  <acceptance_criteria>
+    - synth/mixer.go contains `func PanGains(p float64) (gainL, gainR float64)`
+    - synth/mixer.go contains `func StereoFramesToInt16Bytes(frames [][2]float64) []byte`
+    - synth/mixer.go contains `math.Cos(angle), math.Sin(angle)` (constant-power, not linear)
+    - synth/mixer.go contains `func clamp(v float64) float64`
+    - synth/mixer_test.go contains `TestPanGainsCenter`
+    - synth/mixer_test.go contains `TestStereoFramesToInt16Bytes`
+    - `go test ./synth/... -run "TestPan|TestStereo|TestClamp"` exits 0
+  </acceptance_criteria>
+  <done>Constant-power pan law produces correct L/R gains for all positions. Stereo frames convert to interleaved int16 LE bytes with clamping. All tests pass.</done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: OscillatorBank — multi-layer rendering from WindowSnapshot</name>
+  <files>synth/bank.go, synth/bank_test.go</files>
+  <read_first>
+    - synth/config.go (ClassFreqConfigs, GainPerLayer, SamplesPerWindow, NumLayers)
+    - synth/layer.go (NewLayer, UpdateTarget, AdvanceSample)
+    - synth/mixer.go (PanGains)
+    - classify/types.go (AllClasses, WindowSnapshot)
+    - .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (Pattern 6: per-window render loop)
+    - .planning/phases/02-audio-synthesis-engine/02-CONTEXT.md (D-10: fixed 1/11 gain)
+  </read_first>
+  <behavior>
+    - TestNewBankHas11Layers: NewBank() creates exactly 11 layers, one per TrafficClass
+    - TestRenderWindowOutputLength: RenderWindow with any snapshot returns exactly SamplesPerWindow (22050) stereo frames
+    - TestRenderWindowSilentWhenNoTraffic: RenderWindow with empty counts (all zeros, no class ever seen) produces all-zero frames
+    - TestRenderWindowNonZeroWithTraffic: RenderWindow with ClassICMP count=100 produces non-zero L and R samples
+    - TestMixerNoClip: RenderWindow with ALL 11 classes at max count — no frame has |L| > 1.0 or |R| > 1.0 (D-10 guarantees this)
+    - TestStereoPan: RenderWindow with only ClassDHCP (pan=-0.75) — left channel RMS > right channel RMS (wide-left)
+    - TestMultipleWindowsEMAConvergence: RenderWindow called 5 times with same snapshot — later windows have higher amplitude than first (EMA ramp-up)
+  </behavior>
+  <action>
+**synth/bank.go** — The core synthesis engine. Per D-10, each layer gets GainPerLayer (1/11) of headroom:
+
+```go
+package synth
+
+import "github.com/netsynth/netsynth/classify"
+
+// OscillatorBank holds 11 synthesis layers, one per TrafficClass.
+// It consumes WindowSnapshot data and renders stereo PCM frames.
+type OscillatorBank struct {
+    layers map[classify.TrafficClass]*Layer
+    tau    float64
+}
+
+// NewBank creates an OscillatorBank with one Layer per TrafficClass.
+// tau is the EMA time constant in seconds (use 1.0 for D-07's "1-2 second" feel).
+func NewBank(tau float64) *OscillatorBank {
+    b := &OscillatorBank{
+        layers: make(map[classify.TrafficClass]*Layer, NumLayers),
+        tau:    tau,
+    }
+    for _, class := range classify.AllClasses() {
+        cfg := ClassFreqConfigs[class]
+        b.layers[class] = NewLayer(cfg, SampleRate, tau)
+    }
+    return b
+}
+
+// RenderWindow updates amplitude targets from snap, then renders SamplesPerWindow
+// stereo frames. Each frame is [2]float64{left, right} with values in [-1, 1].
+func (b *OscillatorBank) RenderWindow(snap classify.WindowSnapshot) [][2]float64 {
+    // Find max count for normalization
+    var maxCount int64
+    for _, count := range snap.Counts {
+        if count > maxCount {
+            maxCount = count
+        }
+    }
+
+    // Update target amplitudes for all layers
+    for _, class := range classify.AllClasses() {
+        count := snap.Counts[class]
+        b.layers[class].UpdateTarget(count, maxCount)
+    }
+
+    // Render frames
+    frames := make([][2]float64, SamplesPerWindow)
+    for i := range frames {
+        var sumL, sumR float64
+        for _, class := range classify.AllClasses() {
+            layer := b.layers[class]
+            sample := layer.AdvanceSample()
+            gainL, gainR := PanGains(layer.Config.Pan)
+            sumL += sample * GainPerLayer * gainL
+            sumR += sample * GainPerLayer * gainR
+        }
+        frames[i] = [2]float64{sumL, sumR}
+    }
+    return frames
+}
+```
+
+Key design points:
+- `GainPerLayer` (1/11) is applied during mixing, not in the layer (per D-10). This ensures 11 max-amplitude layers sum to exactly 1.0.
+- `classify.AllClasses()` is used for iteration order consistency.
+- The `AdvanceSample()` call both advances the oscillator phase AND applies EMA smoothing (from layer.go).
+
+Write tests FIRST (RED), then implementation (GREEN).
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/yoloyolo && go test ./synth/... -run "TestNewBank|TestRenderWindow|TestMixerNoClip|TestStereoPan|TestMultipleWindows" -v -count=1</automated>
+  </verify>
+  <acceptance_criteria>
+    - synth/bank.go contains `func NewBank(tau float64) *OscillatorBank`
+    - synth/bank.go contains `func (b *OscillatorBank) RenderWindow(snap classify.WindowSnapshot) [][2]float64`
+    - synth/bank.go contains `GainPerLayer` (the 1/11 gain applied per layer)
+    - synth/bank.go imports `github.com/netsynth/netsynth/classify`
+    - synth/bank_test.go contains `TestMixerNoClip`
+    - synth/bank_test.go contains `TestStereoPan`
+    - synth/bank_test.go contains `TestRenderWindowOutputLength`
+    - `go test ./synth/...` exits 0 (full synth package passes)
+  </acceptance_criteria>
+  <done>OscillatorBank renders 22050 stereo frames per window. 11 layers mixed with 1/11 gain never clip. Panned sources produce asymmetric L/R output. EMA converges over multiple windows. All synth tests pass.</done>
+</task>
+
+</tasks>
+
+<verification>
+- `go test ./synth/... -v` passes all tests (config, oscillator, layer, mixer, bank)
+- No test contains a TODO or Skip marker
+- `grep -r "GainPerLayer" synth/bank.go` confirms fixed-gain mixing
+- `grep "PanGains" synth/mixer.go synth/bank.go` confirms pan is used in both files
+</verification>
+
+<success_criteria>
+- OscillatorBank creates 11 layers from ClassFreqConfigs and renders stereo PCM from WindowSnapshot
+- Constant-power panning produces correct L/R gains per D-12 positions
+- Fixed 1/11 gain per layer prevents clipping by construction (D-10)
+- Int16 byte conversion with clamping ready for go-lame encoder
+- All synth/ tests pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/02-audio-synthesis-engine/02-02-SUMMARY.md`
+</output>