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.

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:

Requirements invalidated? -> Move to Out of Scope with reason
Requirements validated? -> Move to Validated with phase reference
New requirements emerged? -> Add to Active
Decisions to log? -> Add to Key Decisions
"What This Is" still accurate? -> Update if drifted

After each milestone:

Full review of all sections
Core Value check — still the right priority?
Audit Out of Scope — reasons still valid?
Update Context with current state

Last updated: 2026-03-26 after v1.1 milestone start

4.6 KiB Raw Blame History