gurix/yoloyolo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
gurix
2026-03-26 11:36:43 +01:00
parent 0e74f94782
commit 08f1a87a54
4 changed files with 1002 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/02-audio-synthesis-engine/02-01-PLAN.md
+372
View File
@@ -0,0 +1,372 @@
---
phase: 02-audio-synthesis-engine
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- synth/config.go
- synth/oscillator.go
- synth/layer.go
- synth/config_test.go
- synth/layer_test.go
- go.mod
- go.sum
autonomous: true
requirements: [SYNTH-01, SYNTH-02]
must_haves:
truths:
- "Each of 11 traffic classes has a unique frequency, harmonic profile, and pan position defined"
- "Phase-accumulator oscillator produces non-zero PCM samples with harmonics"
- "EMA amplitude smoothing moves current amplitude toward target over time"
- "Whisper floor prevents amplitude from reaching zero once a class has been seen"
- "go-lame v0.0.9 is in go.mod and CGo build succeeds"
artifacts:
- path: "synth/config.go"
provides: "FreqConfig, HarmonicDef types and ClassFreqConfigs table for all 11 classes"
contains: "ClassFreqConfigs"
- path: "synth/oscillator.go"
provides: "Phase-accumulator oscillator with Advance method"
contains: "func (o *Oscillator) Advance"
- path: "synth/layer.go"
provides: "Layer struct with EMA amplitude, whisper floor, target updates"
contains: "func (l *Layer) UpdateTarget"
key_links:
- from: "synth/config.go"
to: "classify/types.go"
via: "import classify.TrafficClass as map key"
pattern: "map\\[classify\\.TrafficClass\\]FreqConfig"
- from: "synth/layer.go"
to: "synth/oscillator.go"
via: "Layer embeds/uses Oscillator"
pattern: "Oscillator"
---
<objective>
Build the synthesis foundation: frequency/harmonic config table, phase-accumulator oscillator, and EMA amplitude layer — all with tests. Also install gcc, ffprobe, and go-lame dependency.
Purpose: SYNTH-01 (distinct drone layers) and SYNTH-02 (amplitude dynamics) depend on these building blocks. Everything in this plan is tested in isolation before the mixer and encoder are built in Plan 02.
Output: `synth/config.go`, `synth/oscillator.go`, `synth/layer.go` with corresponding test files. Environment ready for CGo builds.
</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/STATE.md
@.planning/phases/02-audio-synthesis-engine/02-CONTEXT.md
@.planning/phases/02-audio-synthesis-engine/02-RESEARCH.md
@classify/types.go
<interfaces>
<!-- From classify/types.go — the input contract for synthesis -->
From classify/types.go:
```go
type TrafficClass string
const (
ClassICMP TrafficClass = "ICMP"
ClassDNS TrafficClass = "DNS"
ClassHTTPS TrafficClass = "HTTPS"
ClassHTTP TrafficClass = "HTTP"
ClassSSH TrafficClass = "SSH"
ClassSMTP TrafficClass = "SMTP"
ClassNTP TrafficClass = "NTP"
ClassDHCP TrafficClass = "DHCP"
ClassOtherTCP TrafficClass = "other-TCP"
ClassOtherUDP TrafficClass = "other-UDP"
ClassUnknown TrafficClass = "unknown"
)
func AllClasses() []TrafficClass { ... }
type WindowSnapshot struct {
Counts map[TrafficClass]int64
TotalPackets int64
WindowIndex int
}
```
</interfaces>
</context>
<tasks>
<task type="auto">
<name>Task 1: Environment setup and dependency installation</name>
<files>go.mod, go.sum</files>
<read_first>
- go.mod (current dependencies)
- .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (environment notes)
</read_first>
<action>
1. Confirm Go is available. Check `which go` — if not found, check common paths: `/usr/local/go/bin/go`, `/home/dev/tools/go-install/go/bin/go`, or install via `sudo apt-get install -y golang-go`. Export PATH so `go` is accessible for subsequent commands.
2. Install gcc (required for sjzar/go-lame CGo build):
```
sudo apt-get update && sudo apt-get install -y gcc
```
3. Install ffprobe (required for MP3 validation in tests):
```
sudo apt-get install -y ffmpeg
```
4. Add go-lame to go.mod:
```
go get github.com/sjzar/go-lame@v0.0.9
```
5. Run `go mod tidy` to clean up.
6. Verify CGo build works by running `CGO_ENABLED=1 go build ./...` — should succeed with no errors.
NOTE: Do NOT add go-audio/wav. Per research recommendation, skip the WAV intermediate and write PCM bytes directly to LameWriter. This eliminates a dependency and avoids the io.WriteSeeker complication.
</action>
<verify>
<automated>go version && gcc --version && ffprobe -version && grep "go-lame" go.mod && CGO_ENABLED=1 go build ./...</automated>
</verify>
<acceptance_criteria>
- `go version` outputs a version string containing "go1.2"
- `gcc --version` outputs a version string
- `ffprobe -version` outputs a version string
- go.mod contains the line `github.com/sjzar/go-lame v0.0.9`
- `CGO_ENABLED=1 go build ./...` exits 0
</acceptance_criteria>
<done>Go, gcc, and ffprobe are available. go-lame v0.0.9 is in go.mod. CGo build succeeds.</done>
</task>
<task type="auto" tdd="true">
<name>Task 2: Synth config, oscillator, and layer with tests</name>
<files>synth/config.go, synth/oscillator.go, synth/layer.go, synth/config_test.go, synth/layer_test.go</files>
<read_first>
- classify/types.go (TrafficClass constants, AllClasses, WindowSnapshot)
- .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (patterns 1-2, frequency table, EMA formula)
- .planning/phases/02-audio-synthesis-engine/02-CONTEXT.md (decisions D-01 through D-09)
</read_first>
<behavior>
- TestAllClassesHaveConfig: Every class from classify.AllClasses() has an entry in ClassFreqConfigs
- TestFrequenciesInRange: All BaseHz values are within 60-800 Hz (per D-01)
- TestFrequenciesUnique: No two classes share the same BaseHz
- TestHarmonicsNonEmpty: Every class has at least 2 HarmonicDef entries (fundamental + at least 1 harmonic, per D-05)
- TestPanPositionsInRange: All Pan values in [-1.0, 1.0]
- TestOscillatorAdvance: Oscillator at 440 Hz / 44100 SR produces non-zero samples; 100 samples have both positive and negative values (sine wave)
- TestOscillatorPhaseWrap: After 44100 advances, phase stays in [0, 1)
- TestOscillatorDistinctFreqs: Oscillators at 65 Hz and 440 Hz produce different sample sequences
- TestEMAAmplitudeRise: Layer with target=1.0 and currentAmp=0.0 has currentAmp > 0.5 after 44100 samples (1 second at tau=1.0)
- TestEMAAmplitudeDecay: Layer with target=0.03 (whisper floor) and currentAmp=1.0 has currentAmp < 0.5 after 44100 samples
- TestWhisperFloor: Layer marked as seen=true with target set from zero-count snapshot has targetAmp >= whisperFloor (0.03)
- TestWhisperFloorNotSeenIsZero: Layer with seen=false has targetAmp == 0.0
</behavior>
<action>
**synth/config.go** — Create the frequency/harmonic/pan configuration table. Per D-01 through D-06 and D-11/D-12:
```go
package synth
import "github.com/netsynth/netsynth/classify"
const (
SampleRate = 44100 // D-13: CD quality
WindowMs = 500 // matches aggregate.DefaultWindowMs
SamplesPerWindow = SampleRate * WindowMs / 1000 // 22050
NumLayers = 11
GainPerLayer = 1.0 / float64(NumLayers) // D-10: ~0.0909
WhisperFloor = 0.03 // D-08/D-09: 3% of max amplitude
)
type HarmonicDef struct {
Ratio int // harmonic number: 1=fundamental, 2=octave, 3=fifth+octave, etc.
Amplitude float64 // relative weight
}
type FreqConfig struct {
BaseHz float64
Harmonics []HarmonicDef
Pan float64 // [-1, 1]: -1=full left, 0=center, +1=full right
}
// ClassFreqConfigs maps each traffic class to its synthesis parameters.
// Frequencies use musical intervals per D-02/D-03. Harmonics per D-05/D-06.
// Pan positions per D-12.
var ClassFreqConfigs = map[classify.TrafficClass]FreqConfig{
classify.ClassICMP: {65.0, []HarmonicDef{{1, 1.0}, {2, 0.4}, {3, 0.15}}, 0.0},
classify.ClassDNS: {110.0, []HarmonicDef{{1, 1.0}, {2, 0.5}, {3, 0.25}}, -0.2},
classify.ClassHTTPS: {175.0, []HarmonicDef{{1, 1.0}, {2, 0.6}, {3, 0.3}}, 0.2},
classify.ClassHTTP: {220.0, []HarmonicDef{{1, 1.0}, {2, 0.5}, {4, 0.2}}, -0.35},
classify.ClassSSH: {330.0, []HarmonicDef{{1, 1.0}, {3, 0.6}, {5, 0.3}}, 0.35},
classify.ClassSMTP: {440.0, []HarmonicDef{{1, 1.0}, {2, 0.3}, {3, 0.1}}, -0.55},
classify.ClassNTP: {520.0, []HarmonicDef{{1, 1.0}, {2, 0.25}}, 0.55},
classify.ClassDHCP: {600.0, []HarmonicDef{{1, 1.0}, {2, 0.35}, {3, 0.15}}, -0.75},
classify.ClassOtherTCP: {700.0, []HarmonicDef{{1, 1.0}, {2, 0.2}}, 0.75},
classify.ClassOtherUDP: {780.0, []HarmonicDef{{1, 1.0}, {2, 0.2}}, -0.75},
classify.ClassUnknown: {437.0, []HarmonicDef{{1, 1.0}, {2, 0.8}, {3, 0.4}}, 0.0},
// D-04: 437 Hz is ~12 cents flat from A4 (440 Hz/SMTP).
// Creates 3 Hz beating when SMTP is present = dissonant "doesn't belong" signal.
}
```
**synth/oscillator.go** — Phase-accumulator oscillator (Pattern 1 from research):
```go
package synth
import "math"
type Oscillator struct {
phase float64
freq float64
sr float64
}
func NewOscillator(freq float64, sampleRate int) *Oscillator {
return &Oscillator{freq: freq, sr: float64(sampleRate)}
}
// Advance returns one sample: fundamental + harmonics summed and normalized to [-1, 1].
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
}
return 0
}
// Phase returns the current phase (for testing).
func (o *Oscillator) Phase() float64 {
return o.phase
}
```
**synth/layer.go** — Layer with EMA amplitude smoothing (Pattern 2):
```go
package synth
import "math"
// EMAAlpha computes the per-sample smoothing coefficient for a given time constant.
// tau=1.0 at SR=44100 gives alpha ~0.0000227 (63% of target reached in 1 second). Per D-07.
func EMAAlpha(tau float64, sampleRate int) float64 {
return 1.0 - math.Exp(-1.0/(tau*float64(sampleRate)))
}
type Layer struct {
Config FreqConfig
Osc *Oscillator
currentAmp float64
targetAmp float64
alpha float64 // EMA coefficient
seen bool // whether this class has ever had count > 0
whisper float64 // whisper floor amplitude (D-08)
}
func NewLayer(cfg FreqConfig, sampleRate int, tau float64) *Layer {
return &Layer{
Config: cfg,
Osc: NewOscillator(cfg.BaseHz, sampleRate),
alpha: EMAAlpha(tau, sampleRate),
whisper: WhisperFloor,
}
}
// UpdateTarget sets the target amplitude from a packet count and max count across all classes.
// Per D-07/D-08/D-09: once seen, floor is whisper; amplitude scales linearly with normalized rate.
func (l *Layer) UpdateTarget(count int64, maxCount int64) {
if count > 0 {
l.seen = true
}
if !l.seen {
l.targetAmp = 0.0
return
}
normalizedRate := 0.0
if maxCount > 0 {
normalizedRate = float64(count) / float64(maxCount)
}
l.targetAmp = l.whisper + (1.0-l.whisper)*normalizedRate
}
// AdvanceSample renders one sample and advances the EMA amplitude toward target.
// Returns the raw mono sample (before pan/gain).
func (l *Layer) AdvanceSample() float64 {
sample := l.Osc.Advance(l.Config.Harmonics)
l.currentAmp += l.alpha * (l.targetAmp - l.currentAmp)
return sample * l.currentAmp
}
// CurrentAmp returns the current amplitude (for testing).
func (l *Layer) CurrentAmp() float64 {
return l.currentAmp
}
// TargetAmp returns the target amplitude (for testing).
func (l *Layer) TargetAmp() float64 {
return l.targetAmp
}
// Seen returns whether this layer has ever received traffic (for testing).
func (l *Layer) Seen() bool {
return l.seen
}
```
Write tests FIRST (RED), then create the implementation files (GREEN). Run `go test ./synth/...` after each.
</action>
<verify>
<automated>cd /home/dev/workspace/yoloyolo && go test ./synth/... -v -count=1</automated>
</verify>
<acceptance_criteria>
- synth/config.go contains `var ClassFreqConfigs = map[classify.TrafficClass]FreqConfig{`
- synth/config.go contains `WhisperFloor = 0.03`
- synth/config.go contains `SampleRate = 44100`
- synth/config.go contains `GainPerLayer`
- synth/oscillator.go contains `func (o *Oscillator) Advance(harmonics []HarmonicDef) float64`
- synth/oscillator.go contains `o.phase -= 1.0` (NOT math.Mod)
- synth/layer.go contains `func (l *Layer) UpdateTarget(count int64, maxCount int64)`
- synth/layer.go contains `func (l *Layer) AdvanceSample() float64`
- synth/layer.go contains `l.whisper + (1.0-l.whisper)*normalizedRate`
- synth/config_test.go contains `TestAllClassesHaveConfig`
- synth/config_test.go contains `TestFrequenciesInRange`
- synth/layer_test.go contains `TestEMAAmplitudeRise`
- synth/layer_test.go contains `TestWhisperFloor`
- `go test ./synth/...` exits 0
</acceptance_criteria>
<done>All 11 traffic classes have config entries with unique frequencies in 60-800 Hz. Oscillator produces correct waveform samples. EMA amplitude smoothing converges toward target with whisper floor enforcement. All tests pass.</done>
</task>
</tasks>
<verification>
- `go test ./synth/... -v` passes all tests
- `CGO_ENABLED=1 go build ./...` succeeds (gcc + go-lame working)
- `grep -c "ClassFreqConfigs" synth/config.go` returns at least 1
- Every class from `classify.AllClasses()` has config entry (verified by TestAllClassesHaveConfig)
</verification>
<success_criteria>
- synth/config.go defines FreqConfig for all 11 TrafficClass values with frequencies in 60-800 Hz range
- synth/oscillator.go implements phase-accumulator with harmonic rendering
- synth/layer.go implements EMA amplitude smoothing with whisper floor
- All tests in synth/ pass
- gcc, ffprobe, and go-lame are installed and working
</success_criteria>
<output>
After completion, create `.planning/phases/02-audio-synthesis-engine/02-01-SUMMARY.md`
</output>