yoloyolo/README.md

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