yoloyolo/.planning/phases/02-audio-synthesis-engine/02-RESEARCH.md

# Phase 2: Audio Synthesis Engine - Research

**Researched:** 2026-03-26
**Domain:** Go additive audio synthesis, stereo MP3 encoding, EMA amplitude smoothing, WAV intermediate format
**Confidence:** HIGH — decisions are locked, stack is pre-determined in CLAUDE.md, all API signatures verified against official pkg.go.dev docs.

---

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

**Tone mapping**
- D-01: Wide ambient frequency range: 60-800 Hz across 11 traffic classes
- D-02: Frequencies use musical intervals (harmonic relationships — fifths, octaves, etc.) so layers blend pleasantly
- D-03: Approximate register assignments: ICMP ~65 Hz (deep bass), DNS ~110 Hz, HTTPS ~175 Hz, HTTP ~220 Hz, SSH ~330 Hz, SMTP ~440 Hz, NTP ~520 Hz, DHCP ~600 Hz, other-TCP/other-UDP ~700-800 Hz
- D-04: "unknown" traffic gets a dissonant/detuned tone — slightly off-key or beating frequency

**Waveform texture**
- D-05: Each drone layer uses fundamental + 2-3 harmonics (not pure sine waves)
- D-06: Harmonic ratios vary per traffic class for subtle timbral distinction

**Amplitude dynamics**
- D-07: EMA smoothing with medium responsiveness (1-2 second attack/decay)
- D-08: Layers never fade to full silence — once seen, stays at a fixed whisper floor (~2-5% of max amplitude)
- D-09: Fixed whisper floor (not recency-based decay)

**Mixing and output**
- D-10: Fixed equal gain per layer — each of 11 layers gets 1/11 of headroom (~0.09 max amplitude)
- D-11: Stereo output with register-based panning: bass center, mid spread L/R, high frequencies wider
- D-12: Panning positions: ICMP center, DNS slight-L, HTTPS slight-R, HTTP center-L, SSH center-R, SMTP mid-L, NTP mid-R, DHCP wide-L, other-TCP wide-R, other-UDP wide-L, unknown center
- D-13: 44100 Hz sample rate (CD quality)
- D-14: 128 kbps MP3 encoding via `sjzar/go-lame`
- D-15: `-o` flag for output path; defaults to `netsynth-<timestamp>.mp3` when omitted
- D-16: Empty (zero-packet) input produces a clear error message, not a corrupt or zero-byte MP3

### Claude's Discretion
- Exact Hz values per class (within the 60-800 Hz range, using musical intervals)
- Specific harmonic ratios per traffic class (within the "2-3 harmonics" constraint)
- Exact EMA alpha/decay constants to achieve the 1-2 second feel
- Exact whisper floor percentage (within 2-5% range)
- WAV intermediate format usage (per CLAUDE.md recommendation of go-audio/wav)
- Stereo panning implementation (constant-power pan law vs linear)

### Deferred Ideas (OUT OF SCOPE)
None — discussion stayed within phase scope.
</user_constraints>

---

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| SYNTH-01 | Each traffic class generates a distinct ambient/drone layer (layered sine/harmonic waves) | Additive synthesis pattern: oscillator struct with phase accumulator, harmonic table, per-class config |
| SYNTH-02 | Drone layer amplitudes evolve over time windows based on traffic volume per class | EMA update pattern: α derived from window duration; amplitude target driven by WindowSnapshot.Counts |
| SYNTH-03 | Multiple drone layers are mixed into a single coherent audio stream without distortion | Fixed-gain mixer: 1/11 per layer guarantees sum ≤ 1.0; constant-power stereo panning; go-audio/wav → go-lame pipeline |
| OUT-01 | User can specify output file path via `-o` flag (defaults to `netsynth-<timestamp>.mp3`) | Cobra `StringVarP` flag; `time.Now().Format` for timestamp default |
| OUT-02 | Output is encoded as a valid MP3 file | `sjzar/go-lame` LameWriter: set params → InitParams() → Write([]byte PCM) → Close() |
| OUT-03 | Empty captures (zero packets) produce a clear error instead of a corrupt file | Check `totalPackets == 0` before encoding; return descriptive `fmt.Errorf` instead |
</phase_requirements>

---

## Summary

Phase 2 builds the complete audio pipeline: oscillator bank → EMA amplitude smoother → stereo mixer → WAV buffer → LAME MP3 encoder. It operates against synthetic `classify.WindowSnapshot` inputs — no live capture is involved. All major library choices are locked in CLAUDE.md and prior research: `sjzar/go-lame` v0.0.9 for MP3, `go-audio/wav` for the intermediate format, hand-rolled additive synthesis, and Cobra for the `-o` flag.

The synthesis architecture is well-understood from Phase 1 research. The core math is: for each window, compute a target amplitude per traffic class from packet counts, advance the EMA toward that target, render N PCM samples (fundamental + 2-3 harmonics with class-specific ratios), apply constant-power stereo panning into L/R channels, mix the 11 layers, write stereo interleaved int16 samples to a WAV buffer, and encode to MP3 via go-lame at 44100 Hz / 128 kbps / 2 channels.

Two environmental blockers need Wave 0 tasks: `gcc` and `ffprobe` are not installed. `gcc` is required to build `sjzar/go-lame` (CGo). `ffprobe` is needed for the success criterion that validates the MP3 output. Both are available via `apt` on this machine.

**Primary recommendation:** Build `synth/`, `encode/`, and extend `cmd/` as three independent Go packages. Test each in isolation using table-driven tests with synthetic `WindowSnapshot` inputs and PCM buffer assertions before wiring to the full pipeline in Phase 3.

---

## Standard Stack

### Core (locked by CLAUDE.md)

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `github.com/sjzar/go-lame` | v0.0.9 | MP3 encoding via embedded LAME C source | Locked. Embeds libmp3lame; no system dep. CGO_ENABLED=1 required. |
| `github.com/go-audio/wav` | latest | WAV file I/O as PCM intermediate buffer | Locked. Simplifies PCM → LAME pipeline; decouples synthesis from encoding. |
| `github.com/spf13/cobra` | v1.10.2 | `-o` flag; already in go.mod | Already wired in main.go. |
| Hand-rolled additive synthesis | — | Oscillator, amplitude EMA, mixer | Locked. `go-audio/generator` archived 2026-02-01; no library adds value. |

**go-lame is NOT yet in go.mod.** Wave 0 must add it.

**go-audio/wav is NOT yet in go.mod.** Wave 0 must add it.

**Installation:**
```bash
# Requires PATH to Go binary (see environment notes)
go get github.com/sjzar/go-lame@v0.0.9
go get github.com/go-audio/wav@latest
```

---

## Architecture Patterns

### Recommended Package Structure

```
synth/
├── config.go        # FreqConfig struct: frequency table, harmonic ratios, pan positions
├── oscillator.go    # Phase-accumulator sine oscillator, Harmonics() render method
├── layer.go         # Layer struct: Oscillator + EMA amplitude state per TrafficClass
├── bank.go          # OscillatorBank: 11 layers, Update(WindowSnapshot), Render(N frames) → [][2]float64
└── mixer.go         # Sum layers L+R, convert float64 → int16 interleaved (stereo)
encode/
└── mp3.go           # NewMP3Encoder(path, sampleRate, bitrate) → writes WAV buffer → LAME encode → file
cmd/netsynth/
└── main.go          # Add -o flag, zero-packet guard, wire synth bank → encode
```

### Pattern 1: Phase-Accumulator Oscillator with Harmonics

**What:** Each oscillator maintains a `phase float64` that advances by `freq/sampleRate` per sample, wrapping at 1.0. `math.Sin(2π * phase)` yields the fundamental. Harmonics at integer multiples use the same phase scaled by harmonic ratio.

**Why:** Avoids `math.Sin(2π * freq * t / sampleRate)` which loses floating-point precision over long runs. Phase accumulator stays near zero, preserving accuracy indefinitely.

**Example:**
```go
// Source: standard DSP practice; verified against Dylan Meeus audio-from-scratch series
type Oscillator struct {
    phase float64
    freq  float64
    sr    float64
}

// Advance returns one sample (fundamental + harmonics summed and normalized).
func (o *Oscillator) Advance(harmonics []HarmonicDef) float64 {
    sum := 0.0
    totalWeight := 0.0
    for _, h := range harmonics {
        sum += h.Amplitude * math.Sin(2*math.Pi*o.phase*float64(h.Ratio))
        totalWeight += h.Amplitude
    }
    o.phase += o.freq / o.sr
    if o.phase >= 1.0 {
        o.phase -= 1.0
    }
    if totalWeight > 0 {
        return sum / totalWeight // normalize to [-1, 1]
    }
    return 0
}
```

### Pattern 2: EMA Amplitude Smoothing

**What:** On each `WindowSnapshot`, compute a `targetAmplitude` for each layer. The current amplitude moves toward target each audio sample using coefficient `α`. α is derived from desired time constant τ (in seconds) and sample rate SR: `α = 1 - exp(-1 / (τ * SR))`.

**Why 1-2 second feel:** With τ = 1.0s and SR = 44100, α ≈ 0.0000227. After τ seconds of samples, amplitude reaches ~63% of target — perceptually "medium responsive." For attack/decay symmetry, use the same α for both directions.

**Formula:**
```go
// Source: standard signal processing; EMA with continuous-time derivation
tau := 1.0 // seconds — Claude's discretion; adjust for 1-2s feel
alpha := 1.0 - math.Exp(-1.0/(tau*float64(sampleRate)))

// Per-sample update (inside render loop):
layer.currentAmp += alpha * (layer.targetAmp - layer.currentAmp)
```

**Whisper floor:** After receiving the first snapshot showing count > 0 for a class, set `layer.whisperFloor = 0.03` (3% — within the 2-5% range). The target amplitude is:
```go
target := whisperFloor + (1.0 - whisperFloor) * normalizedRate
// where normalizedRate = float64(count) / float64(maxCountSeen)
```

### Pattern 3: Constant-Power Stereo Panning

**What:** Given a pan position `p ∈ [-1, 1]` where -1 = full left, 0 = center, +1 = full right, the per-channel gains are:
```go
// Source: standard audio engineering — constant-power (equal-power) pan law
angle := (p + 1.0) / 2.0 * math.Pi / 2.0  // map [-1,1] → [0, π/2]
gainL := math.Cos(angle)
gainR := math.Sin(angle)
```
Constant-power panning preserves perceived loudness as the signal moves across the stereo field. Linear panning creates a loudness dip at center. Given the ambient nature of this output, constant-power is correct.

**Pan table (from D-12):**
```go
var PanPositions = map[classify.TrafficClass]float64{
    classify.ClassICMP:     0.0,   // center
    classify.ClassDNS:     -0.2,   // slight-L
    classify.ClassHTTPS:   +0.2,   // slight-R
    classify.ClassHTTP:    -0.35,  // center-L
    classify.ClassSSH:     +0.35,  // center-R
    classify.ClassSMTP:    -0.55,  // mid-L
    classify.ClassNTP:     +0.55,  // mid-R
    classify.ClassDHCP:    -0.75,  // wide-L
    classify.ClassOtherTCP: +0.75, // wide-R
    classify.ClassOtherUDP: -0.75, // wide-L (matches DHCP register)
    classify.ClassUnknown:  0.0,   // center (stand out via dissonance, not position)
}
```

### Pattern 4: WAV Buffer → LAME Pipeline

**What:** Render all PCM samples to an `audio.IntBuffer` (via `go-audio/wav`), write to a `bytes.Buffer` as WAV, then pass the raw PCM bytes to `sjzar/go-lame`'s `LameWriter.Write()`.

**Why WAV intermediate:** Decouples synthesis timing from LAME's CGo overhead. The entire PCM block is available before encoding starts, which is correct for a batch-output tool. WAV also serves as a debug artifact — save it alongside the MP3 during development.

**go-lame API (verified against pkg.go.dev):**
```go
// Source: pkg.go.dev/github.com/sjzar/go-lame — verified 2026-03-26
import "github.com/sjzar/go-lame"

outFile, _ := os.Create(outputPath)
defer outFile.Close()

wr := lame.NewWriter(outFile)
wr.Encoder.SetInSamplerate(44100)
wr.Encoder.SetOutSamplerate(44100)
wr.Encoder.SetNumChannels(2)       // stereo
wr.Encoder.SetBitrate(128)
wr.Encoder.SetQuality(5)
wr.Encoder.InitParams()            // MUST call after all Set* calls

// PCM input format: int16 little-endian interleaved stereo bytes
// Render: []int16{L0, R0, L1, R1, ...} → convert to []byte → Write
pcmBytes := int16SliceToBytes(interleavedSamples)
wr.Write(pcmBytes)
wr.Close()  // flushes LAME internal buffer, writes final MP3 frames
```

**CRITICAL:** `InitParams()` must be called after all configuration `Set*` calls and before the first `Write`. Skipping it produces corrupted MP3 output.

**int16 conversion:**
```go
import "encoding/binary"

func int16SliceToBytes(samples []int16) []byte {
    buf := make([]byte, len(samples)*2)
    for i, s := range samples {
        binary.LittleEndian.PutUint16(buf[i*2:], uint16(s))
    }
    return buf
}
```

### Pattern 5: Harmonic Config Table

**What:** A static table maps each `TrafficClass` to its `FreqConfig`. Defined in `synth/config.go`. No magic numbers elsewhere.

**Recommended frequency assignments (Claude's discretion, within D-01 to D-04 constraints):**

The user specified approximate Hz values. Musical intervals starting from 65 Hz (ICMP as the bass root):
- 65 Hz is close to C2 (musical bass). Intervals: fifth = ×1.5, octave = ×2, major third ≈ ×1.25, minor third ≈ ×1.2.

```go
// Source: derived from D-03 constraints using musical interval ratios
type HarmonicDef struct {
    Ratio     int     // harmonic number (1 = fundamental, 2 = octave, 3 = fifth+octave)
    Amplitude float64 // relative weight
}

type FreqConfig struct {
    BaseHz    float64
    Harmonics []HarmonicDef
    Pan       float64 // from PanPositions table
}

var ClassFreqConfigs = map[classify.TrafficClass]FreqConfig{
    // Deep bass — pure, minimal harmonics (pad feel)
    classify.ClassICMP: {65.0, []HarmonicDef{{1, 1.0}, {2, 0.4}, {3, 0.15}}, 0.0},
    // Sub-bass — slightly brighter
    classify.ClassDNS: {110.0, []HarmonicDef{{1, 1.0}, {2, 0.5}, {3, 0.25}}, -0.2},
    // Warm mid-bass — HTTPS is the most common traffic, warm pad
    classify.ClassHTTPS: {175.0, []HarmonicDef{{1, 1.0}, {2, 0.6}, {3, 0.3}}, 0.2},
    // Mid — HTTP slightly brighter than HTTPS
    classify.ClassHTTP: {220.0, []HarmonicDef{{1, 1.0}, {2, 0.5}, {4, 0.2}}, -0.35},
    // SSH — buzzy (odd harmonics emphasized for character)
    classify.ClassSSH: {330.0, []HarmonicDef{{1, 1.0}, {3, 0.6}, {5, 0.3}}, 0.35},
    // SMTP — clean tone
    classify.ClassSMTP: {440.0, []HarmonicDef{{1, 1.0}, {2, 0.3}, {3, 0.1}}, -0.55},
    // NTP — high, pure
    classify.ClassNTP: {520.0, []HarmonicDef{{1, 1.0}, {2, 0.25}}, 0.55},
    // DHCP — wide stereo, brighter
    classify.ClassDHCP: {600.0, []HarmonicDef{{1, 1.0}, {2, 0.35}, {3, 0.15}}, -0.75},
    // other-TCP — high, minimal harmonics
    classify.ClassOtherTCP: {700.0, []HarmonicDef{{1, 1.0}, {2, 0.2}}, 0.75},
    // other-UDP
    classify.ClassOtherUDP: {780.0, []HarmonicDef{{1, 1.0}, {2, 0.2}}, -0.75},
    // unknown — detuned (beating frequency: fundamental + 1.03× = ~3Hz beat at 440Hz)
    classify.ClassUnknown: {437.0, []HarmonicDef{{1, 1.0}, {2, 0.8}, {3, 0.4}}, 0.0},
    // The 437 Hz combined with its 2nd harmonic at 874 Hz creates beating against
    // any SMTP (440 Hz) present in the mix, reinforcing "something doesn't belong"
}
```

Note on "unknown" detuning: 437 Hz is ~12 cents flat from A4 (440 Hz). If SMTP traffic is present, the 3 Hz beat between 437 and 440 is perceptually jarring. The 2nd harmonic at 874 Hz also beats against the SMTP fundamental's second harmonic at 880 Hz — a compound dissonance. This is the correct implementation of D-04.

### Pattern 6: Per-Window Render Loop

**What:** For each received `WindowSnapshot`, update amplitude targets, then render exactly `samplesPerWindow` PCM frames (= `sampleRate * windowDurationMs / 1000`).

```go
// samplesPerWindow = 44100 * 500 / 1000 = 22050 samples per 500ms window
// Each frame = 2 int16 values (L, R) for stereo
samplesPerWindow := sampleRate * windowMs / 1000

func (b *OscillatorBank) RenderWindow(snap classify.WindowSnapshot) [][2]float64 {
    b.updateTargets(snap)  // sets targetAmp per layer from snap.Counts
    frames := make([][2]float64, samplesPerWindow)
    for i := range frames {
        var sumL, sumR float64
        for _, layer := range b.layers {
            sample := layer.osc.Advance(layer.config.Harmonics)
            layer.currentAmp += layer.alpha * (layer.targetAmp - layer.currentAmp)
            gainL, gainR := panGains(layer.config.Pan)
            sumL += sample * layer.currentAmp * layer.gainPerLayer * gainL
            sumR += sample * layer.currentAmp * layer.gainPerLayer * gainR
        }
        frames[i] = [2]float64{sumL, sumR}
    }
    return frames
}
```

**gainPerLayer = 1.0 / 11 ≈ 0.0909** (D-10). With 11 layers each at max amplitude 1.0 and gain 1/11, the theoretical maximum sum is exactly 1.0. Clipping is impossible by construction — no dynamic limiter needed.

### Anti-Patterns to Avoid

- **Calling InitParams() before all Set* calls:** go-lame silently uses defaults for any parameters set after InitParams(). Always configure fully, then call InitParams() once.
- **Using float32 PCM samples directly with go-lame:** go-lame's `Encode` and `Write` expect `[]byte` representing int16 little-endian PCM. Convert float64 samples to int16 with `int16(sample * 32767)` and then to bytes via `encoding/binary`.
- **Writing an empty MP3:** If zero snapshots are received (D-16 / OUT-03), detect this before opening the output file. Opening the file before checking creates a zero-byte file on disk even if encoding fails.
- **Streaming MP3 mid-run:** MP3 VBR headers require finalization. Buffer all PCM then encode at the end. This is the correct pattern for non-interactive output (see REQUIREMENTS.md Out of Scope).
- **Phase accumulator overflow:** Use `phase -= 1.0` (not `math.Mod`) when phase exceeds 1.0. `math.Mod` is slower and introduces floating-point artifacts.
- **go-audio/wav for the final output file:** go-audio/wav requires an `io.WriteSeeker` (must support `Seek`). A `bytes.Buffer` does not implement `Seek`. Use `os.File` or `bytes.Buffer` + manual WAV header if only using WAV as intermediate. Recommended: render PCM to `[]int16`, skip WAV file entirely for production path, write bytes directly to LameWriter.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| MP3 encoding | Custom MP3 framer | `sjzar/go-lame` v0.0.9 | MP3 frame format is complex; ID3 headers, bit reservoir, psychoacoustic model — thousands of edge cases |
| WAV file format | Custom WAV header writer | `go-audio/wav` (optional) or raw int16 bytes direct to go-lame | WAV header has mandatory chunk offsets that must be backpatched; go-audio/wav handles this |
| Musical interval math | Frequency ratio lookup tables | Use the ratios directly: fifth = ×1.5, octave = ×2 | Pre-computed in config table; no runtime math needed |

---

## Common Pitfalls

### Pitfall 1: InitParams() Not Called

**What goes wrong:** `LameWriter.Write()` silently produces empty or corrupted MP3 frames. No panic or error is returned. The MP3 file is created but fails `ffprobe` validation.

**Why it happens:** go-lame wraps libmp3lame's C API which requires explicit parameter initialization. The Go wrapper does not auto-call it.

**How to avoid:** In `encode/mp3.go`, make `NewMP3Encoder()` call `InitParams()` internally after all configuration. Callers never need to know about it.

**Warning signs:** MP3 file is non-zero bytes but `ffprobe` reports "Invalid data found when processing input" or duration is 0.

### Pitfall 2: Stereo Interleaving Order

**What goes wrong:** Left and right channels are swapped or mono is written when stereo is expected. Oscillators that should be wide-right sound wide-left.

**Why it happens:** go-lame expects `[L0, R0, L1, R1, ...]` interleaved. If samples are written as `[L0, L1, ..., R0, R1, ...]` (planar), the decoder interprets the first N/2 bytes as alternating L/R.

**How to avoid:** Interleave explicitly in the frame render loop: `pcm[i*2] = leftSample; pcm[i*2+1] = rightSample`.

### Pitfall 3: EMA Never Reaches Whisper Floor on First Window

**What goes wrong:** During the first window, `currentAmp` starts at 0. If a class has count > 0, the target is above the whisper floor but `currentAmp` starts from 0 — it takes several windows to ramp up. The first second of audio is unnaturally quiet.

**Why it happens:** EMA is a smoothing filter — it takes time to respond from zero.

**How to avoid:** Initialize `currentAmp = whisperFloor` for all layers at startup (not 0). This way all layers start at their floor, not silence. D-08 specifies the floor is always present once a class has been seen — pre-setting to whisper floor on construction is consistent with the intent.

### Pitfall 4: go-audio/wav Requires io.WriteSeeker

**What goes wrong:** Passing `bytes.Buffer` as the writer to `wav.NewEncoder` causes a compile error or runtime panic because `bytes.Buffer` does not implement `Seek`.

**Why it happens:** WAV format must backpatch header chunk sizes after the data is written. This requires seeking backwards in the file.

**How to avoid:** Either write PCM bytes directly to `LameWriter` (skip WAV entirely) or use a `bytes.Buffer` subtype that supports seeking. The simplest production path: render float64 samples → convert to int16 → convert to []byte → `LameWriter.Write()`. The WAV intermediate is optional for debugging.

### Pitfall 5: Zero-Packet Guard Must Precede File Creation

**What goes wrong:** The output file (`netsynth-<timestamp>.mp3`) is created on disk, then the zero-packet check fires and returns an error. A zero-byte file is left behind. Confusing to users.

**Why it happens:** Typical pattern opens the file first, then validates inputs.

**How to avoid:** Collect all `WindowSnapshot` values from the channel into a slice. Check `totalPackets == 0` across all snapshots. Only then open the output file and begin encoding. In Phase 2's isolated testing, this check is performed before passing snapshots to the encoder.

### Pitfall 6: gcc Not Installed

**What goes wrong:** `go build` with `CGO_ENABLED=1` fails with `cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in $PATH`.

**Why it happens:** `sjzar/go-lame` embeds LAME C source and requires CGo compilation. The build environment on this machine does not have `gcc` installed.

**How to avoid:** Wave 0 task must install gcc: `sudo apt-get install -y gcc`.

---

## Environment Availability

| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Go toolchain | All compilation | ✗ | — | Must install; available via apt or tarball |
| gcc / C compiler | `sjzar/go-lame` CGo build | ✗ | — | None — required for go-lame; install via apt |
| ffprobe | OUT-02 test validation (success criterion: "passes ffprobe validation") | ✗ | — | None for automated test; install via apt (ffmpeg package) |
| `sjzar/go-lame` v0.0.9 | MP3 encoding | ✗ (not in go.mod) | — | Wave 0: `go get github.com/sjzar/go-lame@v0.0.9` |
| `go-audio/wav` | WAV intermediate (optional) | ✗ (not in go.mod) | — | Can skip WAV and write PCM bytes directly to LameWriter |

**Note on Go toolchain:** The project's go.mod exists and was used to build Phase 1 successfully. STATE.md records `[Phase 01]: Go installed to /home/dev/tools/go-install/go (no sudo); PATH export required each session`. However, `/home/dev/tools/` does not currently exist on this machine. The Go binary path needs to be confirmed before Wave 0 executes. The module cache location will also affect where `go get` downloads packages.

**Missing dependencies with no fallback:**
- `gcc` — blocks go-lame CGo compilation. Install: `sudo apt-get install -y gcc`
- `ffprobe` — blocks MP3 validation in tests. Install: `sudo apt-get install -y ffmpeg`
- Go toolchain — path unknown; needs confirmation before Wave 0

**Missing dependencies with fallback:**
- `go-audio/wav` — can be skipped; write PCM bytes directly to LameWriter (saves one dependency)

---

## Validation Architecture

### Test Framework

| Property | Value |
|----------|-------|
| Framework | Go standard `testing` package (no external framework) |
| Config file | none — uses `go test ./...` |
| Quick run command | `go test ./synth/... ./encode/...` |
| Full suite command | `go test ./...` |

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| SYNTH-01 | Each class produces a non-zero PCM output with distinct frequency content | unit | `go test ./synth/... -run TestOscillatorDistinct` | ❌ Wave 0 |
| SYNTH-01 | Harmonics produce richer waveform than pure sine | unit | `go test ./synth/... -run TestHarmonics` | ❌ Wave 0 |
| SYNTH-02 | EMA amplitude rises toward target over N samples | unit | `go test ./synth/... -run TestEMAAplitudeRise` | ❌ Wave 0 |
| SYNTH-02 | Whisper floor prevents amplitude reaching zero | unit | `go test ./synth/... -run TestWhisperFloor` | ❌ Wave 0 |
| SYNTH-03 | Mixer sum of 11 max-amplitude layers does not exceed 1.0 | unit | `go test ./synth/... -run TestMixerNoClip` | ❌ Wave 0 |
| SYNTH-03 | Stereo output has distinct L/R channel values for panned sources | unit | `go test ./synth/... -run TestStereoPan` | ❌ Wave 0 |
| OUT-01 | `-o flag` sets output path; default contains timestamp | unit | `go test ./cmd/... -run TestOutputFlag` | ❌ Wave 0 |
| OUT-02 | Encoded bytes form a valid MP3 (ffprobe check) | integration | `go test ./encode/... -run TestMP3Valid` | ❌ Wave 0 |
| OUT-03 | Zero-packet input returns error, no file created | unit | `go test ./encode/... -run TestZeroPacketError` | ❌ Wave 0 |

### Sampling Rate

- **Per task commit:** `go test ./synth/...`
- **Per wave merge:** `go test ./...`
- **Phase gate:** Full suite green before `/gsd:verify-work`

### Wave 0 Gaps

- [ ] `synth/config_test.go` — covers SYNTH-01 (oscillator distinct, harmonics)
- [ ] `synth/layer_test.go` — covers SYNTH-02 (EMA rise, whisper floor)
- [ ] `synth/mixer_test.go` — covers SYNTH-03 (no clip, stereo pan)
- [ ] `encode/mp3_test.go` — covers OUT-02, OUT-03
- [ ] Environment setup: `sudo apt-get install -y gcc ffmpeg` — required before any build
- [ ] `go get github.com/sjzar/go-lame@v0.0.9` — add to go.mod
- [ ] `go get github.com/go-audio/wav@latest` — add to go.mod (if using WAV intermediate)

---

## Code Examples

### Full go-lame Encode Path (Verified)

```go
// Source: pkg.go.dev/github.com/sjzar/go-lame — verified 2026-03-26
import (
    "encoding/binary"
    "os"
    "github.com/sjzar/go-lame"
)

func EncodeMP3(outputPath string, stereoSamples [][2]float64, sampleRate int) error {
    f, err := os.Create(outputPath)
    if err != nil {
        return err
    }
    defer f.Close()

    wr := lame.NewWriter(f)
    wr.Encoder.SetInSamplerate(sampleRate)
    wr.Encoder.SetOutSamplerate(sampleRate)
    wr.Encoder.SetNumChannels(2)
    wr.Encoder.SetBitrate(128)
    wr.Encoder.SetQuality(5)
    wr.Encoder.InitParams() // MUST be called after all Set*

    // Convert [][2]float64 → interleaved int16 bytes
    pcm := make([]byte, len(stereoSamples)*4) // 2 channels * 2 bytes/sample
    for i, frame := range stereoSamples {
        l := int16(frame[0] * 32767)
        r := int16(frame[1] * 32767)
        binary.LittleEndian.PutUint16(pcm[i*4:], uint16(l))
        binary.LittleEndian.PutUint16(pcm[i*4+2:], uint16(r))
    }

    if _, err := wr.Write(pcm); err != nil {
        return err
    }
    return wr.Close()
}
```

### EMA Alpha Calculation

```go
// Source: standard continuous-time EMA derivation
// tau = time constant in seconds (1.0 for 1-second attack/decay feel)
// sampleRate = 44100
func emaAlpha(tau float64, sampleRate int) float64 {
    return 1.0 - math.Exp(-1.0/(tau*float64(sampleRate)))
}
// Result: alpha ≈ 0.0000227 for tau=1.0, SR=44100
// After 44100 samples (1 second): amplitude reaches 63.2% of target
// After 3 seconds: 95% of target — consistent with "medium responsiveness" D-07
```

### Amplitude Target from WindowSnapshot

```go
// Source: derived from D-07, D-08, D-09
func (b *OscillatorBank) updateTargets(snap classify.WindowSnapshot) {
    // Find max count across all classes for normalization
    var maxCount int64
    for _, count := range snap.Counts {
        if count > maxCount {
            maxCount = count
        }
    }

    for _, class := range classify.AllClasses() {
        layer := b.layers[class]
        count := snap.Counts[class]

        // Mark class as "seen" if it has appeared at all
        if count > 0 {
            layer.seen = true
        }

        var target float64
        if layer.seen {
            normalizedRate := 0.0
            if maxCount > 0 {
                normalizedRate = float64(count) / float64(maxCount)
            }
            target = layer.whisperFloor + (1.0-layer.whisperFloor)*normalizedRate
        }
        // If never seen: target stays 0.0 (no whisper floor yet)
        layer.targetAmp = target
    }
}
```

### Zero-Packet Guard (OUT-03)

```go
// Collect all snapshots before encoding
func RunSynthesis(snapshots <-chan classify.WindowSnapshot, outputPath string) error {
    var allSnaps []classify.WindowSnapshot
    var totalPackets int64
    for snap := range snapshots {
        allSnaps = append(allSnaps, snap)
        totalPackets += snap.TotalPackets
    }

    if totalPackets == 0 {
        return fmt.Errorf("no packets captured: output MP3 not written (empty capture produces no audio)")
    }

    // Now safe to open output file and encode
    return encodeAllSnaps(allSnaps, outputPath)
}
```

### Output Flag Wiring in main.go

```go
// Add to main.go — following existing Cobra pattern
var outputPath string

rootCmd.Flags().StringVarP(&outputPath, "output", "o", "", "Output MP3 file path (default: netsynth-<timestamp>.mp3)")

// In run() function — resolve default before synthesis:
if outputPath == "" {
    outputPath = fmt.Sprintf("netsynth-%s.mp3", time.Now().Format("20060102-150405"))
}
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| `go-audio/generator` for oscillators | Hand-rolled phase accumulator | Feb 2026 (archived) | No library dependency; ~20 lines replaces it |
| `google/gopacket` | `gopacket/gopacket` community fork | 2024 | Already using correct fork (in go.mod) |
| Dynamic-linked libmp3lame | `sjzar/go-lame` embedded C source | April 2025 (v0.0.9) | Self-contained CGo; no system package required |

**Deprecated/outdated:**
- `go-audio/generator`: Archived February 2026. Do not use. Already documented in CLAUDE.md.
- `faiface/beep`: Real-time playback focus — irrelevant for batch file output.

---

## Open Questions

1. **Go toolchain location on this machine**
   - What we know: STATE.md says Go was installed to `/home/dev/tools/go-install/go` and PATH export is required each session. But `/home/dev/tools/` does not exist.
   - What's unclear: Was Go installed in this container/environment differently, or does it need re-installation?
   - Recommendation: Wave 0 first task should confirm `which go` or install Go fresh. The `go.mod` and `go.sum` exist, suggesting Go was successfully used for Phase 1.

2. **go-audio/wav vs raw PCM bytes to go-lame**
   - What we know: CLAUDE.md recommends go-audio/wav as intermediate. The WAV library requires `io.WriteSeeker` which `bytes.Buffer` does not satisfy.
   - What's unclear: Whether the planner should include go-audio/wav as a dependency or go direct PCM → LAME.
   - Recommendation: Write PCM as `[]int16` directly to a `[]byte` buffer and pass to `LameWriter.Write()`. This is simpler, eliminates one dependency, and avoids the `io.WriteSeeker` complication. Reserve go-audio/wav for if a WAV debug output feature is wanted later.

3. **Subjective listening validation**
   - What we know: STATE.md flags "Frequency mapping requires subjective listening validation — specific Hz values not determined by research; must test during Phase 2".
   - What's unclear: The plan should allocate a manual listening step. Automated tests can verify PCM is non-zero and distinct across classes, but perceptual quality requires human ears.
   - Recommendation: Include a Wave N task: "Manual listening test — play generated MP3 with synthetic traffic, verify each class is audibly distinct and the stereo field is perceived."

---

## Project Constraints (from CLAUDE.md)

The following directives from `CLAUDE.md` constrain this phase. Plans MUST NOT contradict them.

| Directive | Impact on Phase 2 |
|-----------|-------------------|
| Language: Go — single binary output | No new runtime dependencies; go-lame CGo is compile-time only |
| Audio format: MP3 output (not WAV or raw PCM) | WAV is intermediate only (optional); final output must be .mp3 |
| Non-interactive capture | All PCM is buffered then encoded after capture ends; no streaming |
| `sjzar/go-lame` v0.0.9 — use this, not viert/go-lame or shine-mp3 | Encoder package must import `github.com/sjzar/go-lame` |
| `go-audio/generator` is archived — do NOT use | Oscillator must be hand-rolled (phase accumulator pattern) |
| `faiface/beep`, `dasa.cc/snd` — do NOT use | No real-time audio libraries |
| `go-audio/wav` recommended for intermediate format | Use if WAV intermediate is included; or skip entirely (see Open Question 2) |
| CGO_ENABLED=1 required for go-lame build | Build commands must set CGO_ENABLED=1; gcc must be installed |
| GSD workflow enforcement — use `/gsd:execute-phase` | No direct file edits outside GSD workflow |

---

## Sources

### Primary (HIGH confidence)
- `pkg.go.dev/github.com/sjzar/go-lame` — API signatures, InitParams requirement, LameWriter pattern, PCM byte format — verified 2026-03-26
- `pkg.go.dev/github.com/go-audio/wav` — Encoder API, io.WriteSeeker requirement — verified 2026-03-26
- `/home/dev/workspace/yoloyolo/classify/types.go` — TrafficClass constants, WindowSnapshot struct — direct codebase read
- `/home/dev/workspace/yoloyolo/aggregate/window.go` — Aggregate() signature, channel contract — direct codebase read
- `/home/dev/workspace/yoloyolo/cmd/netsynth/main.go` — existing Cobra flag pattern, pipeline wiring — direct codebase read
- `/home/dev/workspace/yoloyolo/CLAUDE.md` — locked stack decisions, forbidden libraries — direct codebase read

### Secondary (MEDIUM confidence)
- `.planning/research/ARCHITECTURE.md` — pipeline patterns, per-layer amplitude lerp, anti-patterns — project research document from 2026-03-24
- `.planning/research/STACK.md` — library rationale, audio synthesis architecture note — project research document from 2026-03-24
- Standard DSP literature — EMA formula `α = 1 - exp(-1/(τ·SR))`, constant-power pan law `cos/sin` — mathematically stable, textbook-level

### Tertiary (LOW confidence)
- Frequency assignments (specific Hz values) — derived from D-03 constraints using musical interval ratios; require subjective listening validation

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — locked in CLAUDE.md, APIs verified against pkg.go.dev
- Architecture: HIGH — patterns verified from Phase 1 codebase; math is standard DSP
- Pitfalls: HIGH — InitParams trap verified against go-lame API; others from direct API inspection
- Frequency assignments: LOW — require subjective listening test; values are reasonable starting points

**Research date:** 2026-03-26
**Valid until:** 2026-06-26 (stable stack; go-lame and go-audio/wav APIs are stable)