# 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 and offline pcap file sonification.

## 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.0 MVP shipped 2026-03-26.** 3,254 lines of Go across 6 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.

All 16 v1 requirements validated. Full pipeline working: 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

### Active

(None — next milestone requirements TBD)

### Out of Scope

- Real-time audio playback — v1 is file output only
- GUI or web interface — CLI only
- Custom sound mapping configuration — predefined + auto-cluster only
- Rhythmic/percussive output — ambient/drone style only

## 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 traffic classes: 10 known protocols + 4 hash-bucketed unknowns

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

## Evolution

This document evolves at phase transitions and milestone boundaries.

---
*Last updated: 2026-03-26 after v1.0 milestone*