docs: add README with usage, architecture, and build instructions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,150 @@
+# NetSynth
+
+**Turn network traffic into ambient sound.**
+
+NetSynth captures live network traffic (or reads pcap files), classifies packets by protocol, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone. A ping sounds different from HTTPS noise, which sounds different from a port scan.
+
+Run it, let it listen, press Ctrl+C, get an audio fingerprint of your network.
+
+## Quick Start
+
+```bash
+# Live capture on eth0 (requires root or CAP_NET_RAW)
+sudo netsynth -i eth0
+
+# Press Ctrl+C after a few seconds → saves netsynth-<timestamp>.mp3
+
+# Sonify a pcap file (no privileges needed)
+netsynth --read capture.pcap -o output.mp3
+
+# Filter to DNS traffic only
+sudo netsynth -i eth0 --filter "port 53" -o dns.mp3
+```
+
+## Installation
+
+### Prerequisites
+
+- Go 1.24+
+- C compiler (GCC or Clang) — required for MP3 encoding (CGo)
+
+### Build from Source
+
+```bash
+git clone https://codeberg.org/gurix/yoloyolo.git
+cd yoloyolo
+go build -o netsynth ./cmd/netsynth
+```
+
+For a smaller binary:
+
+```bash
+go build -ldflags="-s -w" -o netsynth ./cmd/netsynth
+```
+
+### Privileges
+
+Live packet capture requires elevated privileges on Linux:
+
+```bash
+# Option A: run as root
+sudo ./netsynth -i eth0
+
+# Option B: grant capability (preferred)
+sudo setcap cap_net_raw=eip ./netsynth
+./netsynth -i eth0
+```
+
+## Usage
+
+```
+netsynth [flags]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-i`, `--interface` | Network interface to capture on |
+| `--read` | Read packets from a pcap file instead of live capture |
+| `-o`, `--output` | Output MP3 file path (default: `netsynth-<timestamp>.mp3`) |
+| `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) |
+| `--verbose` | Print per-window protocol activity to stderr |
+| `--list-interfaces` | List available network interfaces and exit |
+
+### Examples
+
+```bash
+# Capture all traffic, verbose per-window output
+sudo netsynth -i wlan0 --verbose
+
+# Only HTTPS traffic
+sudo netsynth -i eth0 --filter "tcp port 443" -o https.mp3
+
+# Sonify a Wireshark capture (output derived: capture.pcap -> capture.mp3)
+netsynth --read capture.pcap
+
+# Filter a pcap file to UDP only
+netsynth --read traffic.pcap --filter "udp" -o udp-only.mp3
+```
+
+## How It Works
+
+NetSynth processes traffic through a four-stage pipeline:
+
+```
+Capture -> Classify -> Aggregate -> Synthesize -> MP3
+```
+
+1. **Capture** — Packets are read from a live interface (via [go-pcap](https://github.com/packetcap/go-pcap)) or a pcap file. Optional BPF filtering reduces the stream to traffic of interest.
+
+2. **Classify** — Each packet is matched against 12 protocol rules (ICMP, DNS, HTTPS, SSH, HTTP, SMTP, NTP, DHCP, etc.). Unrecognized traffic is deterministically hash-bucketed into 4 "unknown" classes so it still produces distinct sounds.
+
+3. **Aggregate** — Classified packets are grouped into 500ms time windows. Each window records per-protocol packet counts that drive synthesis amplitudes.
+
+4. **Synthesize & Encode** — Each traffic class maps to a sine oscillator at a specific frequency and stereo position. Amplitudes rise and fall via EMA smoothing based on traffic volume. All layers are mixed and encoded to MP3 via [LAME](https://github.com/sjzar/go-lame).
+
+### Sound Design
+
+| Traffic Class | Frequency Range | Character |
+|--------------|----------------|-----------|
+| ICMP (Ping) | High register | Bright, distinctive ping tone |
+| DNS | Mid-high | Quick lookup sound |
+| HTTPS/TLS | Low register | Deep, steady drone (bulk traffic) |
+| SSH | Mid register | Distinct interactive tone |
+| HTTP | Low-mid | Warm web traffic hum |
+| Unknown 1-4 | Dissonant | Eerie, attention-grabbing |
+
+Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity.
+
+## Project Structure
+
+```
+cmd/netsynth/   CLI entry point (Cobra)
+capture/        Packet capture, BPF validation, pcap file reading
+classify/       Protocol classification rules and types
+aggregate/      Time-window aggregation and summary output
+synth/          Oscillators, EMA layers, stereo mixer, tone bank
+encode/         MP3 encoding via embedded LAME
+```
+
+## Dependencies
+
+| Library | Purpose |
+|---------|---------|
+| [gopacket/gopacket](https://github.com/gopacket/gopacket) | Packet decoding |
+| [packetcap/go-pcap](https://github.com/packetcap/go-pcap) | Pure Go live capture (no libpcap) |
+| [sjzar/go-lame](https://github.com/sjzar/go-lame) | MP3 encoding (embedded LAME C source) |
+| [spf13/cobra](https://github.com/spf13/cobra) | CLI framework |
+
+No runtime dependencies beyond the compiled binary. CGo is required at build time only (for LAME).
+
+## Testing
+
+```bash
+go test ./... -v
+```
+
+All tests run without root privileges (capture tests use mock data and programmatically generated pcap files).
+
+## License
+
+See [LICENSE](LICENSE) for details.