gurix/yoloyolo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README and PROJECT.md to reflect Phase 6 completion

Browse Source 
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:
gurix
2026-03-26 21:14:30 +01:00
co-authored by Claude Opus 4.6
parent c3d78624ba
commit dddfb1b444
2 changed files with 78 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+77 -11
View File
@@ -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).