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). Major-second frequency ladder (65-3250 Hz) with family-coherent sound design. Group-ordered `--print-config` with section headers. `[groups]` TOML config for reassigning protocols to different sound families. ~6,000 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/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

### 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
- Major-second frequency ladder with family-coherent waveforms and group field on FreqConfig
- Auto-assign frequency range moved to 2500-4000 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
- 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)
- 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 |
| Major-second frequency ladder | Musical interval spacing prevents critical band masking between family members | 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

<details>
<summary>v1.2 Extended Protocol Coverage (shipped 2026-03-27)</summary>

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

</details>

<details>
<summary>v1.1 Custom Sound Mappings (shipped 2026-03-26)</summary>

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

</details>

<details>
<summary>v1.0 MVP (shipped 2026-03-26)</summary>

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

</details>

## 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*