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 shipped. 35 built-in traffic classes across 9 protocol families (Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown). C major pentatonic frequency tuning (just intonation, 65-6534 Hz) with ADSR envelope shaping (sustained vs bursty modes), LFO pitch/tremolo modulation (Eno technique with incommensurable rates), and tanh soft limiter. Group-ordered --print-config with section headers. [groups] TOML config for reassigning protocols to different sound families. ~6,500 lines of Go across 7 packages, full test suite green.

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 v1.0 + v1.1 + v1.2 requirements validated (45 total). Full pipeline: 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 layer with ADSR envelopes, LFO modulation, and pentatonic tuning
• Stereo mixing with constant-power panning and tanh soft limiting
• 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

Validated (v1.2)

• Removed stale constants and future-proofed test bounds for extensibility
• 21 new protocol classifications: Mail (IMAP, POP3, SMTP-sub), File Transfer (FTP, SMB, TFTP), Remote Access (RDP, Telnet, VNC), Database (MySQL, PostgreSQL, Redis, MongoDB), Discovery (mDNS, SSDP, SNMP), VoIP (SIP), Web (QUIC/HTTP3), Infrastructure (LDAP, Kerberos, Syslog)
• No regression in existing 14 protocol classifications
• C major pentatonic frequency tuning (just intonation) with family-coherent waveforms and group field on FreqConfig
• ADSR envelope system: sustained protocols (2s attack, 4s release) and bursty protocols (30ms attack, no sustain)
• LFO modulation: per-group incommensurable pitch wobble and amplitude tremolo (Eno technique)
• Tanh soft limiter on master output prevents clipping
• Auto-assign frequency range moved to 5000-8000 Hz (collision-free with built-ins)
• Group-ordered --print-config output with section headers
• [groups] TOML config for protocol-to-group reassignment

Active

(No active requirements — planning next milestone)

Out of Scope

• Real-time audio playback — file output only
• GUI or web interface — CLI only
• Fully rhythmic/beat-based output — ambient style with percussive accents for bursty protocols
• 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)
• 35 built-in traffic classes across 9 families: Infrastructure, Web, Mail, Remote Access, File Transfer, Database, Discovery, VoIP, Unknown (extensible via custom rules)
• TOML config with partial overrides, unknown-key validation, auto-discovery, and [groups] protocol-to-group reassignment

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
C major pentatonic tuning (just intonation)	Any combination of active tones sounds consonant; replaced major-second ladder	Good
ADSR envelopes over pure EMA	Sustained flows get ambient pads; bursty protocols get percussive accents	Good
LFO with incommensurable rates	Eno technique ensures soundscape never repeats; each group has unique modulation	Good
Tanh soft limiter over hard clipping	Preserves dynamics while preventing distortion during traffic spikes	Good
Group field as string (not enum)	Extensible for new family names without code changes	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

Shipped Milestones

v1.2 Extended Protocol Coverage (shipped 2026-03-27)

35 built-in traffic classes across 9 protocol families with major-second frequency ladder, group-ordered print-config, and [groups] TOML reassignment.

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 v1.2 milestone