diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index b171ee4..4f92474 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -98,6 +98,7 @@ This document evolves at phase transitions and milestone boundaries. 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 diff --git a/README.md b/README.md index 94d64ca..aa491f1 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,9 @@ netsynth --read capture.pcap -o output.mp3 # Filter to DNS traffic only sudo netsynth -i eth0 --filter "port 53" -o dns.mp3 + +# Use a custom sound config +sudo netsynth -i eth0 --config my-sounds.toml ``` ## Installation @@ -67,6 +70,7 @@ netsynth [flags] | `--read` | Read packets from a pcap file instead of live capture | | `-o`, `--output` | Output MP3 file path (default: `netsynth-.mp3`) | | `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) | +| `--config` | Path to a TOML config file for custom sound mappings | | `--verbose` | Print per-window protocol activity to stderr | | `--list-interfaces` | List available network interfaces and exit | @@ -84,8 +88,63 @@ netsynth --read capture.pcap # Filter a pcap file to UDP only netsynth --read traffic.pcap --filter "udp" -o udp-only.mp3 + +# Use a custom sound config +sudo netsynth -i eth0 --config ~/my-sounds.toml ``` +## Custom Sound Configuration + +NetSynth supports TOML config files to override the default sound mappings per traffic class. You can change the frequency and waveform for any class without affecting the others. + +### Config File Discovery + +NetSynth looks for config files in this order (first found wins): + +1. `--config ` flag (error if file does not exist) +2. `./netsynth.toml` in the current working directory +3. `~/.config/netsynth/config.toml` + +If no config is found, NetSynth starts silently with built-in defaults. + +### Config File Format + +```toml +# Override sound settings per traffic class. +# Only the fields you set are changed — everything else keeps its default. + +[sounds.ICMP] +frequency = 80.0 # Hz (default: 65.0) +waveform = "triangle" # sine, square, sawtooth, or triangle + +[sounds.HTTPS] +frequency = 200.0 + +[sounds.DNS] +waveform = "square" +``` + +### Available Traffic Classes + +`ICMP`, `DNS`, `HTTPS`, `HTTP`, `SSH`, `SMTP`, `NTP`, `DHCP`, `OtherTCP`, `OtherUDP`, `Unknown1`, `Unknown2`, `Unknown3`, `Unknown4` + +### Available Waveforms + +| Waveform | Character | +|----------|-----------| +| `sine` | Pure, clean fundamental tone | +| `square` | Hollow, buzzy (odd harmonics) | +| `sawtooth` | Bright, rich (all harmonics) | +| `triangle` | Soft, mellow (odd harmonics, fast rolloff) | + +All waveforms use bandlimited additive synthesis to prevent aliasing artifacts. + +### Validation + +- **Unknown keys** are rejected at startup with an error naming the bad key (catches typos like `frequncy`) +- **Unknown class names** produce a warning but do not prevent startup +- **Invalid waveform values** are rejected with a clear error + ## How It Works NetSynth processes traffic through a four-stage pipeline: @@ -100,20 +159,25 @@ Capture -> Classify -> Aggregate -> Synthesize -> MP3 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). +4. **Synthesize & Encode** — Each traffic class maps to an oscillator at a specific frequency, waveform, 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 | +| Traffic Class | Frequency | Character | +|--------------|-----------|-----------| +| ICMP (Ping) | 65 Hz | Deep, distinctive ping tone | +| DNS | 110 Hz | Quick lookup sound | +| HTTPS/TLS | 175 Hz | Steady drone (bulk traffic) | +| HTTP | 220 Hz | Warm web traffic hum | +| SSH | 330 Hz | Distinct interactive tone | +| SMTP | 440 Hz | Mail delivery tone | +| NTP | 520 Hz | Time sync pulse | +| DHCP | 600 Hz | Network setup sound | +| Other TCP | 700 Hz | Generic TCP hum | +| Other UDP | 780 Hz | Generic UDP hum | +| Unknown 1-4 | 862–1047 Hz | Dissonant, attention-grabbing | -Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity. +Sustained traffic sounds louder; quiet periods fade to silence. The result is a unique audio fingerprint of your network activity. All frequencies and waveforms can be overridden via the [config file](#custom-sound-configuration). ## Project Structure @@ -122,7 +186,8 @@ 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 +synth/ Oscillators, waveforms, EMA layers, stereo mixer, tone bank +config/ TOML config loading, validation, and partial merge encode/ MP3 encoding via embedded LAME ``` @@ -134,6 +199,7 @@ encode/ MP3 encoding via embedded LAME | [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 | +| [BurntSushi/toml](https://github.com/BurntSushi/toml) | TOML config parsing | No runtime dependencies beyond the compiled binary. CGo is required at build time only (for LAME).