docs(02): capture phase context
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
# 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*
|
||||
@@ -0,0 +1,192 @@
|
||||
# Phase 2: Audio Synthesis Engine - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-03-26
|
||||
**Phase:** 02-audio-synthesis-engine
|
||||
**Areas discussed:** Tone mapping, Waveform texture, Amplitude dynamics, Mixing & headroom
|
||||
|
||||
---
|
||||
|
||||
## Tone Mapping
|
||||
|
||||
### Frequency range
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Narrow ambient (80-400 Hz) | Deep, bass-heavy drones — everything in warm low register | |
|
||||
| Wide ambient (60-800 Hz) | Spread across bass to mid range — rich, layered soundscape | ✓ |
|
||||
| Full spectrum (50-2000 Hz) | Bass through high-mid — maximum separation | |
|
||||
|
||||
**User's choice:** Wide ambient (60-800 Hz)
|
||||
**Notes:** None
|
||||
|
||||
### Register assignment
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Keep as shown | HTTPS at ~175 Hz is low enough for bulk drone feel | ✓ |
|
||||
| Swap to match prior rule | Strictly follow bulk=low, control=mid, interactive=high | |
|
||||
| You decide | Let Claude optimize Hz values | |
|
||||
|
||||
**User's choice:** Keep as shown
|
||||
**Notes:** None
|
||||
|
||||
### Tuning approach
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Musical intervals | Harmonic/musical relationships so layers blend pleasantly | ✓ |
|
||||
| Arbitrary spacing | Spread evenly, simpler but may clash | |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Musical intervals
|
||||
**Notes:** None
|
||||
|
||||
### Unknown traffic tone
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Single fixed tone at top of range | Always ~800 Hz | |
|
||||
| Dissonant/detuned tone | Off-key or beating frequency signals unclassified traffic | ✓ |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Dissonant/detuned tone
|
||||
**Notes:** None
|
||||
|
||||
---
|
||||
|
||||
## Waveform Texture
|
||||
|
||||
### Richness
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Pure sine waves | Clean, minimal, ethereal — single frequency per class | |
|
||||
| Sine + 2-3 harmonics | Fundamental + overtones — warm, pad-like, textured | ✓ |
|
||||
| Unique waveform per class | Different harmonic profiles per traffic type | |
|
||||
|
||||
**User's choice:** Sine + 2-3 harmonics
|
||||
**Notes:** None
|
||||
|
||||
### Harmonic ratios
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Same ratios everywhere | All classes use identical harmonic recipe | |
|
||||
| Vary per class | Each class gets different harmonic weights for timbral distinction | ✓ |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Vary per class
|
||||
**Notes:** None
|
||||
|
||||
---
|
||||
|
||||
## Amplitude Dynamics
|
||||
|
||||
### Responsiveness
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Slow, glacial (2-4 sec) | Layers swell and fade gradually like weather | |
|
||||
| Medium (1-2 sec) | Noticeable response, still smooth | ✓ |
|
||||
| Snappy (0.5-1 sec) | Layers track traffic closely, more reactive | |
|
||||
|
||||
**User's choice:** Medium (1-2 sec)
|
||||
**Notes:** None
|
||||
|
||||
### Zero-traffic behavior
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fade to full silence | Only active traffic produces sound | |
|
||||
| Fade to a whisper | Barely-audible trace remains for any seen protocol | ✓ |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Fade to a whisper
|
||||
**Notes:** None
|
||||
|
||||
### Whisper floor type
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fixed floor | Once seen, stays at fixed very-low amplitude (2-5%) | ✓ |
|
||||
| Recency-based decay | Whisper fades further over time based on recency | |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Fixed floor
|
||||
**Notes:** None
|
||||
|
||||
---
|
||||
|
||||
## Mixing & Headroom
|
||||
|
||||
### Mix strategy
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fixed equal gain | Each layer gets 1/N headroom (~0.09 max) | ✓ |
|
||||
| Weighted gain by priority | Bulk traffic gets more headroom | |
|
||||
| Dynamic limiter | No fixed gain, soft-clip if exceeds headroom | |
|
||||
|
||||
**User's choice:** Fixed equal gain
|
||||
**Notes:** None
|
||||
|
||||
### Sample rate
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| 44100 Hz (CD quality) | Standard, LAME native | ✓ |
|
||||
| 22050 Hz (half rate) | Smaller files, still fine for <800 Hz | |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** 44100 Hz
|
||||
**Notes:** None
|
||||
|
||||
### MP3 bitrate
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| 128 kbps | Good quality, ~1 MB/min | ✓ |
|
||||
| 192 kbps | Higher quality, ~1.5 MB/min | |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** 128 kbps
|
||||
**Notes:** None
|
||||
|
||||
### Channel mode
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Mono | Single channel, simpler | |
|
||||
| Stereo with panning | Each class panned for spatial separation | ✓ |
|
||||
|
||||
**User's choice:** Stereo with panning
|
||||
**Notes:** None
|
||||
|
||||
### Panning approach
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Fixed positions by register | Bass center, mid spread, high wider | ✓ |
|
||||
| Even spread | All 11 evenly from hard L to hard R | |
|
||||
| You decide | Claude picks | |
|
||||
|
||||
**User's choice:** Fixed positions by register
|
||||
**Notes:** ICMP center, DNS slight-L, HTTPS slight-R, etc.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Exact Hz values per class (within 60-800 Hz, musical intervals)
|
||||
- Specific harmonic ratios per traffic class
|
||||
- Exact EMA alpha/decay constants for 1-2 sec feel
|
||||
- Exact whisper floor percentage (2-5%)
|
||||
- WAV intermediate format usage
|
||||
- Stereo panning implementation method
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope
|
||||
Reference in New Issue
Block a user