yoloyolo/.planning/PROJECT.md

NetSynth

What This Is

A Go CLI tool that captures live network traffic on an interface, classifies packets by protocol, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Supports live capture with BPF filtering, offline pcap file sonification, and fully customizable sound mappings via TOML config.

Core Value

Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan.

Current State

v1.2 in progress. Phase 8 (Test and Constant Cleanup) complete 2026-03-27 — stale NumLayers/GainPerLayer constants removed, test bounds future-proofed for extended frequency range. ~4,675 lines of Go across 7 packages.

Tech stack: gopacket/gopacket v1.5.0, packetcap/go-pcap (pure Go capture), sjzar/go-lame v0.0.9 (embedded LAME), spf13/cobra v1.10.2, BurntSushi/toml v1.6.0.

All 16 v1.0 requirements + 11 v1.1 requirements + CLEAN-01 validated. Full pipeline with customizable sound mappings: capture -> classify -> aggregate -> synthesize -> MP3.

Requirements

Validated (v1.0)

• Capture live packets from a specified network interface until Ctrl+C
• Classify packets by known protocols (ICMP, DNS, HTTPS, SSH, etc.) with 12 predefined rules
• Auto-cluster unrecognized traffic into 4 hash-bucketed unknown classes with distinct tones
• Aggregate traffic into 500ms time windows driving amplitude evolution
• End-to-end pipeline: capture -> classify -> synthesize -> MP3 output
• Map each traffic class to a distinct ambient/drone layer (sine oscillators + EMA smoothing)
• Stereo mixing with constant-power panning, no distortion
• MP3 encoding via embedded LAME, zero-packet guard
• CLI with -i, -o, --list-interfaces, --verbose, --filter, --read flags
• BPF capture filter for scoping live traffic
• Offline pcap file sonification with timestamp-based windowing

Validated (v1.1)

• TOML config file with partial override semantics (frequency, waveform per class)
• Auto-discovery: ./netsynth.toml, ~/.config/netsynth/config.toml
• --config flag for explicit config path (error if missing)
• Unknown-key validation with clear error naming the typo'd key
• Four waveform types: sine, square, sawtooth, triangle (bandlimited)
• User-defined classification rules via [[rules]] TOML blocks
• User rules prepend before built-ins (first-match-wins priority)
• Auto-frequency assignment for custom class names (no silent gaps)
• --print-config outputs effective config as commented TOML

Active

(See REQUIREMENTS.md for v1.2 requirements)

Out of Scope

• Real-time audio playback — file output only
• GUI or web interface — CLI only
• Rhythmic/percussive output — ambient/drone style only
• Stereo position configuration — add in future if requested

Context

• Built in Go (CGO_ENABLED=1 for LAME), single binary output
• Packet capture requires root/CAP_NET_RAW on Linux
• Pure Go capture layer (no libpcap dependency)
• MP3 encoding embeds LAME C source (no system library needed)
• 14 built-in traffic classes: 10 known protocols + 4 hash-bucketed unknowns (extensible via custom rules)
• TOML config with partial overrides, unknown-key validation, auto-discovery

Constraints

• Language: Go — user preference, single binary output
• Privileges: Packet capture requires root/CAP_NET_RAW on Linux
• Audio format: MP3 output (not WAV or raw PCM)
• Interaction model: Non-interactive capture (run -> Ctrl+C -> file saved)

Key Decisions

Decision	Rationale	Outcome
Go over Python/Rust	User preference, single binary, good perf	Good
Ambient/drone style	Layered tones better represent continuous traffic patterns	Good
Predefined + auto-cluster	Known protocols get recognizable sounds; unknown traffic still represented	Good
File output only	Simpler v1, avoids real-time audio complexity	Good
go-pcap over libpcap	Pure Go, no CGo for capture, cross-compilation friendly	Good
go-lame (embedded C) over shine-mp3	Better quality, smaller files, acceptable CGo tradeoff	Good
Hand-rolled synthesis over audio libraries	20 lines of oscillator code, no unnecessary dependencies	Good
Hash-bucketed unknowns over k-means	Deterministic, zero-config, sufficient for v1 audio distinction	Good
Ordered []Rule classifier over switch	Configurable, extensible, first-match-wins semantics	Good
500ms window duration	Balances temporal resolution against snapshot frequency for synthesis	Good
BurntSushi/toml over manual parsing	Industry-standard Go TOML library, Undecoded() catches typos	Good
Pointer fields for partial overrides	*float64, *string distinguish "not set" from zero values	Good
Bandlimited additive synthesis	Prevents aliasing in square/sawtooth/triangle without FFT overhead	Good
FNV-32a hash for auto-frequency	Deterministic, collision-resistant, maps to unused 1200-2350 Hz range	Good
LoadResult struct over tuple return	Clean single return value, extensible for future fields	Good
--print-config as flag (not subcommand)	Consistent with --list-interfaces pattern, simpler CLI surface	Good

Current Milestone: v1.2 Extended Protocol Coverage

Goal: Expand traffic classification with grouped protocol families that share recognizable sound signatures

Target features:

• Research common network protocols and identify missing ones beyond the current 10
• Group related protocols into families (Mail, Web, Remote Access, Database, Discovery, File Transfer, VoIP)
• Within-group sound design: shared base frequency, different waveforms or slight detuning
• Frequency rebalancing to accommodate new classes without overcrowding the spectrum
• New classification rules for all identified protocols
• Updated --print-config output reflecting groups

Shipped Milestones

v1.1 Custom Sound Mappings (shipped 2026-03-26)

Users can customize how traffic sounds via a TOML config file — frequency, waveform, custom classification rules, and config inspection.

v1.0 MVP (shipped 2026-03-26)

Full capture -> classify -> synthesize -> MP3 pipeline with 14 traffic classes, BPF filtering, and pcap sonification.

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition:

1. Requirements invalidated? -> Move to Out of Scope with reason
2. Requirements validated? -> Move to Validated with phase reference
3. New requirements emerged? -> Add to Active
4. Decisions to log? -> Add to Key Decisions
5. "What This Is" still accurate? -> Update if drifted
6. Update README.md to reflect the current state of the project (features, usage, installation)

After each milestone:

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-03-27 after Phase 8 completion