docs: update README and PROJECT.md to reflect Phase 6 completion
Add custom sound configuration section covering TOML config files, auto-discovery, available waveforms, and validation behavior. Update flags table, project structure, dependencies, and sound design table with accurate frequencies. Add README update step to evolution checklist. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -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
|
||||
|
||||
@@ -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-<timestamp>.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 <path>` 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).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user