yoloyolo/.planning/research/SUMMARY.md

Project Research Summary

Project: NetSynth Domain: Network traffic sonification CLI — Go, packet capture, audio synthesis, MP3 encoding Researched: 2026-03-24 Confidence: MEDIUM-HIGH

Executive Summary

NetSynth is a Go CLI tool that captures live network traffic, classifies packets by protocol, and synthesizes an ambient drone MP3 where each protocol layer produces a distinct tonal frequency whose amplitude evolves with traffic volume. There is no direct precedent for this exact form factor: comparable tools (SoNSTAR, Peep, Network-Sonification) all produce real-time audio through OS audio APIs rather than file output, are not single binaries, and do not auto-cluster unknown traffic. The recommended approach builds on well-understood Go concurrency primitives (channel-connected pipeline stages, ticker-driven time windows) rather than audio or ML libraries — the synthesis math is ~100 lines of Go and no external audio framework adds value for batch file output.

The recommended stack is gopacket/gopacket v1.5.0 (community fork, not the abandoned Google repo) for packet decode, packetcap/go-pcap for pure-Go live capture on Linux/macOS, sjzar/go-lame v0.0.9 for embedded-CGo MP3 encoding, and spf13/cobra v1.10.2 for CLI structure. The audio synthesis layer should be hand-rolled — additive sine oscillators with exponential-moving-average amplitude smoothing. This stack requires CGo at build time but produces a self-contained binary with no runtime library dependencies beyond CAP_NET_RAW or root for packet capture.

The two hardest risks are at opposite ends of the pipeline. On the capture side: privilege requirements, CGo binary distribution contracts, and kernel buffer drops all bite in production but not in local development. On the audio side: PCM integer overflow, perceptual tone masking between protocol frequencies, and LAME initialization order all produce silent or subtle corruption that integration tests must specifically cover. Both risk clusters must be resolved in Phase 1 and Phase 2 respectively — they cannot be retrofitted.

Key Findings

Recommended Stack

The stack is straightforward for Go developers with one critical trap: github.com/google/gopacket is unmaintained (270 open issues, no active merges since 2022) and must never be used — the import path is github.com/gopacket/gopacket (community fork, v1.5.0, Go 1.24+ required). For the capture backend, packetcap/go-pcap is pure Go and eliminates libpcap CGo entirely; the MP3 encoder sjzar/go-lame embeds LAME C source and requires CGo but no system library on the target machine. Audio synthesis should be written directly — no audio library is appropriate for batch file output. See .planning/research/STACK.md for full alternatives matrix.

Core technologies:

• github.com/gopacket/gopacket v1.5.0: packet decode (ICMP, DNS, TCP, UDP, TLS layers) — only maintained Go packet library
• github.com/packetcap/go-pcap: live capture backend — pure Go, mmap ring buffer, Linux/macOS, no CGo
• github.com/sjzar/go-lame v0.0.9: MP3 encoding — embeds LAME C source, no runtime .so dependency, requires CGo at build time
• github.com/spf13/cobra v1.10.2: CLI flag parsing — industry standard, handles signal plumbing and help generation
• github.com/go-audio/wav: WAV intermediate format — decouples synthesis from encoding, provides debug artifact
• Hand-rolled additive synthesizer: 30-50 lines of Go sine oscillators, no library needed

Expected Features

NetSynth has a well-defined feature set. All precedent tools provide real-time audio output, not file output — this is both a differentiator and a source of user confusion to address in UX copy. Auto-clustering of unknown traffic is unique to NetSynth among comparable tools. See .planning/research/FEATURES.md for full prioritization matrix and competitor analysis.

Must have (table stakes):

• Interface selection (-i eth0) and --list-interfaces — packet capture CLI convention
• Live capture with graceful Ctrl+C stop producing a valid MP3 — core interaction model
• Per-protocol sound distinction: ICMP, DNS, TCP/443, TCP/other, UDP — minimum fingerprint set
• Ambient drone synthesis with time-windowed amplitude evolution — core differentiator
• MP3 encoding and file output with sensible default filename — deliverable artifact
• Capture statistics summary on exit (stderr) — expected by every capture tool user
• Privilege error detection with actionable message — prevents silent failure
• Minimum viable duration guard — zero-packet capture must not produce a corrupt file

Should have (competitive):

• Auto-clustering of unrecognized traffic into stable drone layers — honest representation, unique feature
• BPF capture filter (--filter) — power user scope control
• Offline pcap file input (--read) — historical analysis and demos
• Verbose protocol activity log (--verbose) — debugging and demo use cases
• Configurable time window duration (--window) — tuning for responsiveness vs. smoothness

Defer (v2+):

• Custom sound mapping configuration file — needs user research first; well-chosen defaults cover v1
• Improved clustering (full k-means on flow features) — hash-bucketing is sufficient for v1
• Multi-interface capture — adds deduplication complexity
• Real-time audio playback — anti-feature; triples cross-platform complexity, conflicts with file-output simplicity

Architecture Approach

The architecture is a channel-connected pipeline of five stages, each a goroutine communicating via buffered channels, with a done channel closed on Ctrl+C driving clean shutdown across all stages. The stages are: Capture (pcap handle → chan gopacket.Packet), Classification (rule-based protocol dispatch + unknown traffic bucketer → chan ClassifiedPacket), Aggregation (ticker-driven time-window accumulator → chan WindowSnapshot), Synthesis (per-class sine oscillators with EMA amplitude smoothing → PCM blocks), and Encoding (LAME encoder goroutine consuming PCM blocks, separate from synthesis to decouple CGo latency). This is the idiomatic Go pipeline pattern and directly follows the build order the architecture research prescribes. See .planning/research/ARCHITECTURE.md for full data flow diagrams and channel buffer size recommendations.

Major components:

1. capture/ — pcap handle wrapper; privilege/interface boundary; all downstream code is pcap-free
2. classify/ — protocol rule dispatch + feature-hash bucketer for unknown traffic; testable with synthetic packets
3. aggregate/ — ticker-driven time-window accumulator; the only stateful time-domain component
4. synth/ — sine oscillators + EMA amplitude smoothing + mixer; pure PCM math, no I/O
5. encode/ — CGo LAME boundary; decoupled encoder goroutine; if encoder changes, only this package changes
6. config/ — static frequency-to-protocol mapping table; prevents magic numbers in synth/

Critical Pitfalls

Nine pitfalls identified, ranging from critical (causes data corruption or broken binaries) to moderate (causes poor audio quality). The top five require architectural decisions in Phase 1 or Phase 2 — they cannot be patched later without significant rewrite. See .planning/research/PITFALLS.md for recovery strategies and the full "Looks Done But Isn't" checklist.

1. Wrong gopacket fork (google/ vs gopacket/) — use github.com/gopacket/gopacket from day one; import path migration across the whole codebase is the recovery cost
2. CGo breaking the single-binary promise — decide the static vs. dynamic linking strategy before writing capture code; verify with ldd on a clean Alpine container in CI
3. CAP_NET_RAW + nosuid filesystem = silent failure — install to /usr/local/bin for capability mode; always provide a sudo ./netsynth fallback with clear error messaging
4. PCM integer overflow producing wrap-around distortion — synthesize internally in float64 [-1.0, 1.0], clamp before casting to int16; never do audio math in integer types
5. Perceptual tone masking (all protocols in the same frequency band) — design the frequency table with register separation: low drones for bulk traffic, mid for control, high for interactive; use harmonic intervals not arithmetic spacing

Implications for Roadmap

Based on research, the architecture's build-order prescription maps directly to a three-phase roadmap. Each phase is independently testable before the next is wired in.

Phase 1: Capture and Classification Pipeline

Rationale: The packet capture layer carries the highest technical risk (privilege, CGo, binary distribution, buffer overflow). Validating it first — before any audio code exists — means the hardest pitfalls are resolved while the codebase is small. The architecture research explicitly names this as the correct first step.

Delivers: A working CLI that opens a network interface, classifies packets by protocol, and prints a live traffic summary to stderr. No audio output yet — just proof the pipeline works. The privilege error message and --list-interfaces flag ship here.

Addresses: Interface selection, live capture, protocol classification, privilege detection, --list-interfaces, capture statistics

Avoids: Wrong gopacket fork (Pitfall 1), CGo distribution contract (Pitfall 2), CAP_NET_RAW binary location (Pitfall 3), packet buffer overflow (Pitfall 4), ZeroCopy use-after-free (Pitfall 5)

Phase 2: Audio Synthesis Engine

Rationale: The synthesis engine is pure PCM math with no pcap dependency. It can be built and tested in isolation with synthetic WindowSnapshot inputs before any real traffic flows through it. This is the architecture research's explicit recommendation. Separating synthesis from capture also means audio bugs are diagnosed without needing a live network.

Delivers: A synthesizer that accepts WindowSnapshot inputs and produces a valid MP3 file. End-to-end smoke test: silence input → ffprobe-validated MP3 output. The frequency mapping table, EMA amplitude smoothing, and the LAME encoder goroutine all ship here.

Uses: sjzar/go-lame, go-audio/wav, hand-rolled oscillator, config/mapping.go frequency table

Implements: synth/ (oscillator, layer, mixer), encode/ (LAME goroutine), aggregate/ (time-window accumulator), config/ (frequency mapping)

Avoids: LAME initialization errors (Pitfall 6), PCM overflow wrap-around (Pitfall 7), perceptual tone masking (Pitfall 8), time window jitter (Pitfall 9)

Phase 3: Pipeline Integration and CLI Polish

Rationale: Wire the Phase 1 capture/classify pipeline to the Phase 2 synthesis engine via the aggregation layer. Add Ctrl+C shutdown producing a valid MP3 (requires coordinated drain across all goroutines). Add auto-clustering of unknown traffic. Add UX features (progress output, file collision warning, graceful empty-capture error).

Delivers: The complete v1 MVP: live capture → protocol classification + auto-clustering → time-windowed synthesis → MP3 file output. Graceful Ctrl+C with valid MP3. Full UX surface (startup interface announcement, per-window progress line, exit statistics).

Addresses: Auto-clustering, graceful Ctrl+C stop, capture statistics, progress feedback, output file collision warning, zero-packet guard, main.go pipeline wiring

Uses: All Phase 1 and Phase 2 components; muesli/kmeans or hash-bucketing for unknown traffic clustering

Phase 4: Power User Features (v1.x)

Rationale: These features add value for specific user segments but have no blocking dependencies on each other — add in any order based on user feedback after the core is validated.

Delivers: BPF capture filter (--filter), offline pcap file input (--read), verbose protocol log (--verbose), configurable time window (--window), configurable output duration for pcap input (--duration)

Addresses: All P2 features from the prioritization matrix in FEATURES.md

Phase Ordering Rationale

• Capture before synthesis: The privilege and CGo pitfalls are foundational — an audio-first approach would hide them until integration and make them expensive to fix.
• Synthesis in isolation: Pure PCM math is independently testable. Building it against synthetic inputs before real traffic makes audio bugs fast to diagnose.
• Integration as its own phase: The shutdown coordination (Ctrl+C → drain → flush encoder → close file) across five goroutines is non-trivial; it deserves focused attention rather than being an afterthought of feature development.
• Power features deferred: BPF filter and offline pcap do not validate the core concept; they add complexity to the capture layer that should wait until the pipeline is stable.

Research Flags

Phases likely needing deeper research during planning:

• Phase 2 (Audio Synthesis): The perceptual frequency mapping table requires listening tests, not just code correctness. Research the auditory masking literature before finalizing config/mapping.go. Consider consulting the SoNSTAR PLOS One paper on time window choices.
• Phase 3 (Auto-clustering): The decision between simple hash-bucketing and k-means clustering (muesli/kmeans) depends on what "meaningfully distinct drone layers" means in practice. This needs a working synthesis engine to evaluate — defer the decision to Phase 3 planning.
• Phase 4 (Offline pcap): Time-compression of multi-hour pcap files to a fixed audio duration needs a clear algorithm decision (proportional window scaling vs. fixed window with truncation). Research this when Phase 4 is planned.

Phases with standard patterns (skip research-phase):

• Phase 1 (Capture pipeline): Go channel pipelines and gopacket usage are thoroughly documented. The pitfalls are known and avoidable with the guidance in PITFALLS.md.
• Phase 3 (Pipeline integration): Go done-channel shutdown patterns are canonical (Go Blog: Pipelines). No novel research needed.

Confidence Assessment

Area	Confidence	Notes
Stack	HIGH	Core libraries confirmed via pkg.go.dev; version numbers verified; go-audio/generator archived status confirmed February 2026
Features	MEDIUM	Niche domain with few direct CLI comparators; feature set derived from tcpdump conventions and sonification research, not user surveys
Architecture	MEDIUM-HIGH	Go pipeline patterns are HIGH confidence (official Go Blog); audio synthesis architecture inferred from SoNSTAR paper (MEDIUM, abstract-level access only)
Pitfalls	HIGH	Packet capture pitfalls verified against official gopacket issues and libpcap docs; audio pitfalls cross-referenced against DSP literature and encoder post-mortems

Overall confidence: MEDIUM-HIGH

Gaps to Address

• Frequency mapping validation: The correct frequency assignments for the protocol drone layers require subjective listening tests with real traffic. The research prescribes the approach (register separation, harmonic intervals) but not specific Hz values. Validate during Phase 2 with a listening session before Phase 3 integration.
• Auto-clustering granularity: How many unknown-traffic clusters are perceptually useful? The research suggests hash-bucketing is acceptable for v1, but does not validate how many distinct cluster tones are distinguishable simultaneously. Validate during Phase 3 with real mixed traffic.
• muesli/kmeans maintenance status: Last release July 2022 (LOW confidence on ongoing maintenance). If Go 1.24 compatibility issues emerge, the alternative is mpraski/clusters (online clustering) or a hand-rolled hash bucketer. Plan for substitution.
• macOS privilege model: CAP_NET_RAW pitfall was verified for Linux. macOS uses a different privilege model (BPF device permissions). If macOS is a target, verify the privilege flow and error messages during Phase 1.

Sources

Primary (HIGH confidence)

• github.com/gopacket/gopacket releases — v1.5.0 November 2025, Go 1.24+ confirmed
• pkg.go.dev/github.com/packetcap/go-pcap — pure Go, Linux/macOS confirmed
• pkg.go.dev/github.com/sjzar/go-lame — v0.0.9 April 2025, embedded C source confirmed
• pkg.go.dev/github.com/spf13/cobra — v1.10.2 December 2025
• Go Blog: Pipelines and cancellation — canonical Go pipeline pattern
• google/gopacket issue #1016 — unmaintained status confirmed
• google/gopacket issue #329 — 98% packet drop under high traffic, afpacket solution
• linuxvox.com: CAP_NET_RAW + nosuid filesystem behavior

Secondary (MEDIUM confidence)

• SoNSTAR PLOS One paper (arXiv 1712.07029) — time window design and sonification architecture
• braheezy.github.io: Go MP3 encoding options — shine-mp3 not production-grade
• Dylan Meeus: Audio From Scratch With Go — PCM synthesis patterns
• github.com/go-audio/generator — archived February 2026, do not use (confirmed read-only)

Tertiary (LOW confidence)

• muesli/kmeans v0.3.1 (July 2022) — last release date only; ongoing Go 1.24 compatibility unverified
• Drone auralization model, Acta Acustica 2024 — amplitude/frequency modulation patterns (MEDIUM, used for perceptual guidance)

---

Research completed: 2026-03-24 Ready for roadmap: yes