114 lines
5.7 KiB
Markdown
114 lines
5.7 KiB
Markdown
# Phase 2: Audio Synthesis Engine - Context
|
|
|
|
**Gathered:** 2026-03-26
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Oscillators, EMA amplitude smoothing, multi-layer mixing, stereo panning, and MP3 encoding — all validated against synthetic `WindowSnapshot` inputs. No live traffic flows through this phase. The output is a valid MP3 file produced from fabricated traffic data.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation 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 that audibly signals unclassified traffic, distinct from the harmonious known classes
|
|
|
|
### Waveform texture
|
|
- **D-05:** Each drone layer uses fundamental + 2-3 harmonics (not pure sine waves) for warm, pad-like sound
|
|
- **D-06:** Harmonic ratios vary per traffic class for subtle timbral distinction — e.g., ICMP brighter, HTTPS warmer, SSH buzzier. Each protocol has its own sonic identity beyond just pitch.
|
|
|
|
### Amplitude dynamics
|
|
- **D-07:** EMA smoothing with medium responsiveness (1-2 second attack/decay). Traffic changes are audible but smooth — not glacial, not snappy.
|
|
- **D-08:** Layers never fade to full silence — once a traffic class has been seen, it stays at a fixed whisper floor (~2-5% of max amplitude). Quiet network still has a faint base layer.
|
|
- **D-09:** Fixed whisper floor (not recency-based decay). Simple and predictable.
|
|
|
|
### Mixing & output
|
|
- **D-10:** Fixed equal gain per layer — each of 11 layers gets 1/11 of headroom (~0.09 max amplitude). Sum never exceeds 1.0, no clipping, no dynamic limiter needed.
|
|
- **D-11:** Stereo output with register-based panning: bass frequencies center, mid frequencies spread left/right, higher frequencies wider. Unknown stays center to stand out.
|
|
- **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)
|
|
|
|
</decisions>
|
|
|
|
<canonical_refs>
|
|
## Canonical References
|
|
|
|
**Downstream agents MUST read these before planning or implementing.**
|
|
|
|
### Project context
|
|
- `.planning/PROJECT.md` — Core value, constraints (Go, MP3 output, non-interactive)
|
|
- `.planning/REQUIREMENTS.md` — SYNTH-01, SYNTH-02, SYNTH-03, OUT-01, OUT-02, OUT-03
|
|
|
|
### Prior phase
|
|
- `.planning/phases/01-capture-and-classification/01-CONTEXT.md` — Phase 1 decisions; `WindowSnapshot` contract defined here
|
|
- `classify/types.go` — `TrafficClass` constants and `WindowSnapshot` struct (the input contract for synthesis)
|
|
- `aggregate/window.go` — `Aggregate()` function that produces `WindowSnapshot` on 500ms intervals
|
|
|
|
### Stack decisions
|
|
- `.planning/research/STACK.md` — Library recommendations (go-lame, go-audio/wav)
|
|
- `.planning/research/ARCHITECTURE.md` — Pipeline architecture, component boundaries
|
|
- `CLAUDE.md` — Technology stack section with `sjzar/go-lame` v0.0.9 usage, `go-audio/wav` for intermediate format
|
|
|
|
</canonical_refs>
|
|
|
|
<code_context>
|
|
## Existing Code Insights
|
|
|
|
### Reusable Assets
|
|
- `classify.TrafficClass` type and constants (`classify/types.go`) — 11 named classes, used as map keys in WindowSnapshot
|
|
- `classify.AllClasses()` — returns all classes in display order; useful for iterating when setting up oscillator bank
|
|
- `classify.WindowSnapshot` — the input contract: `Counts map[TrafficClass]int64`, `TotalPackets int64`, `WindowIndex int`
|
|
- `aggregate.Aggregate()` — produces `chan WindowSnapshot` on 500ms ticks; Phase 2 consumes this channel
|
|
|
|
### Established Patterns
|
|
- Channel-based pipeline: capture -> classify -> aggregate -> (synthesis goes here)
|
|
- `done <-chan struct{}` for shutdown signaling
|
|
- Buffered channels for stage decoupling (512-buffer capture, 8-buffer aggregate output)
|
|
- io.Writer injection for testable output (used in aggregate/summary.go)
|
|
|
|
### Integration Points
|
|
- Synthesis engine will consume `<-chan classify.WindowSnapshot` from `aggregate.Aggregate()`
|
|
- MP3 output path comes from Cobra CLI flags (already scaffolded in `cmd/netsynth/main.go`)
|
|
- Phase 3 wires these together; Phase 2 tests against synthetic/fabricated WindowSnapshot data
|
|
|
|
</code_context>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Sound should feel like an "ambient synth pad" — warm, layered, organic
|
|
- Unknown traffic should be immediately recognizable as "something doesn't belong" via its dissonant tone
|
|
- The stereo field should create a sense of space — not just mono with volume panning
|
|
- Each protocol should have a sonic identity beyond just pitch (varied harmonic ratios)
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 02-audio-synthesis-engine*
|
|
*Context gathered: 2026-03-26*
|