gurixandClaude Opus 4.6
dddfb1b444
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>
111 lines
5.2 KiB
Markdown
111 lines
5.2 KiB
Markdown
# NetSynth
|
|
|
|
## What This Is
|
|
|
|
A Go CLI tool that captures live network traffic on an interface, classifies packets by protocol, and synthesizes an ambient MP3 soundscape where each traffic type produces a distinct harmonic drone or tone. Supports live capture with BPF filtering and offline pcap file sonification.
|
|
|
|
## Core Value
|
|
|
|
Network traffic patterns are instantly recognizable as distinct sounds — a ping sounds different from HTTPS noise, which sounds different from a port scan.
|
|
|
|
## Current State
|
|
|
|
**v1.0 MVP shipped 2026-03-26.** 3,254 lines of Go across 6 packages.
|
|
|
|
Tech stack: gopacket/gopacket v1.5.0, packetcap/go-pcap (pure Go capture), sjzar/go-lame v0.0.9 (embedded LAME), spf13/cobra v1.10.2.
|
|
|
|
All 16 v1 requirements validated. Full pipeline working: capture -> classify -> aggregate -> synthesize -> MP3.
|
|
|
|
**Phase 5 complete 2026-03-26:** Waveform types (sine, square, sawtooth, triangle) with bandlimited synthesis added. OscillatorBank decoupled from global config — NewBank now accepts injected config maps with dynamic gain scaling.
|
|
|
|
**Phase 6 complete 2026-03-26:** TOML config system added. Users can override frequency and waveform per traffic class via `netsynth.toml` (auto-discovered or `--config` flag). Partial overrides, unknown-key validation, and fail-fast startup errors. New `config` package with BurntSushi/toml.
|
|
|
|
## Requirements
|
|
|
|
### Validated (v1.0)
|
|
|
|
- Capture live packets from a specified network interface until Ctrl+C
|
|
- Classify packets by known protocols (ICMP, DNS, HTTPS, SSH, etc.) with 12 predefined rules
|
|
- Auto-cluster unrecognized traffic into 4 hash-bucketed unknown classes with distinct tones
|
|
- Aggregate traffic into 500ms time windows driving amplitude evolution
|
|
- End-to-end pipeline: capture -> classify -> synthesize -> MP3 output
|
|
- Map each traffic class to a distinct ambient/drone layer (sine oscillators + EMA smoothing)
|
|
- Stereo mixing with constant-power panning, no distortion
|
|
- MP3 encoding via embedded LAME, zero-packet guard
|
|
- CLI with `-i`, `-o`, `--list-interfaces`, `--verbose`, `--filter`, `--read` flags
|
|
- BPF capture filter for scoping live traffic
|
|
- Offline pcap file sonification with timestamp-based windowing
|
|
|
|
### Active
|
|
|
|
(See REQUIREMENTS.md for v1.1 requirements)
|
|
|
|
### Out of Scope
|
|
|
|
- Real-time audio playback — file output only
|
|
- GUI or web interface — CLI only
|
|
- Rhythmic/percussive output — ambient/drone style only
|
|
- Stereo position configuration — v1.1 focuses on frequency, waveform, and custom rules
|
|
|
|
## Context
|
|
|
|
- Built in Go (CGO_ENABLED=1 for LAME), single binary output
|
|
- Packet capture requires root/CAP_NET_RAW on Linux
|
|
- Pure Go capture layer (no libpcap dependency)
|
|
- MP3 encoding embeds LAME C source (no system library needed)
|
|
- 14 traffic classes: 10 known protocols + 4 hash-bucketed unknowns
|
|
|
|
## Constraints
|
|
|
|
- **Language**: Go — user preference, single binary output
|
|
- **Privileges**: Packet capture requires root/CAP_NET_RAW on Linux
|
|
- **Audio format**: MP3 output (not WAV or raw PCM)
|
|
- **Interaction model**: Non-interactive capture (run -> Ctrl+C -> file saved)
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| Go over Python/Rust | User preference, single binary, good perf | Good |
|
|
| Ambient/drone style | Layered tones better represent continuous traffic patterns | Good |
|
|
| Predefined + auto-cluster | Known protocols get recognizable sounds; unknown traffic still represented | Good |
|
|
| File output only | Simpler v1, avoids real-time audio complexity | Good |
|
|
| go-pcap over libpcap | Pure Go, no CGo for capture, cross-compilation friendly | Good |
|
|
| go-lame (embedded C) over shine-mp3 | Better quality, smaller files, acceptable CGo tradeoff | Good |
|
|
| Hand-rolled synthesis over audio libraries | 20 lines of oscillator code, no unnecessary dependencies | Good |
|
|
| Hash-bucketed unknowns over k-means | Deterministic, zero-config, sufficient for v1 audio distinction | Good |
|
|
| Ordered []Rule classifier over switch | Configurable, extensible, first-match-wins semantics | Good |
|
|
| 500ms window duration | Balances temporal resolution against snapshot frequency for synthesis | Good |
|
|
|
|
## Current Milestone: v1.1 Custom Sound Mappings
|
|
|
|
**Goal:** Users can customize how traffic sounds via a TOML config file
|
|
|
|
**Target features:**
|
|
- Custom frequency per traffic class (override built-in Hz values)
|
|
- Custom waveform per class (sine, square, sawtooth, triangle)
|
|
- User-defined classification rules with custom sounds
|
|
- Auto-discover config from ./netsynth.toml or ~/.config/netsynth/config.toml
|
|
- --config flag for explicit config path
|
|
|
|
## Evolution
|
|
|
|
This document evolves at phase transitions and milestone boundaries.
|
|
|
|
**After each phase transition:**
|
|
1. Requirements invalidated? -> Move to Out of Scope with reason
|
|
2. Requirements validated? -> Move to Validated with phase reference
|
|
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
|
|
2. Core Value check — still the right priority?
|
|
3. Audit Out of Scope — reasons still valid?
|
|
4. Update Context with current state
|
|
|
|
---
|
|
*Last updated: 2026-03-26 after v1.1 milestone start*
|