21 KiB
Architecture Research
Domain: Network traffic sonification CLI (Go) Researched: 2026-03-24 Confidence: MEDIUM — Go audio synthesis patterns verified via official docs and real libraries; sonification architecture inferred from academic literature (SoNSTAR) and Go concurrency canon.
Standard Architecture
System Overview
┌─────────────────────────────────────────────────────────────┐
│ CLI Entry Point │
│ (flags: interface, output path, duration) │
└───────────────────────────┬─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Capture Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PacketSource (gopacket/pcap) │ │
│ │ Produces: chan Packet │ │
│ └──────────────────────┬──────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
│ raw packet stream
▼
┌─────────────────────────────────────────────────────────────┐
│ Classification Layer │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ Protocol Classifier │ │ Unknown Traffic │ │
│ │ (ICMP, DNS, HTTPS, │ │ Clusterer │ │
│ │ SSH, TCP-other, UDP) │ │ (feature-based bucketer)│ │
│ └───────────┬─────────────┘ └────────────┬────────────┘ │
│ └──────────────┬──────────────┘ │
└─────────────────────────────┼───────────────────────────────┘
│ classified packet events
▼
┌─────────────────────────────────────────────────────────────┐
│ Aggregation Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Time-Window Accumulator │ │
│ │ - fixed window (e.g. 500ms) │ │
│ │ - counts + byte-volume per traffic class │ │
│ │ Produces: chan WindowSnapshot │ │
│ └──────────────────────┬──────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
│ window snapshots
▼
┌─────────────────────────────────────────────────────────────┐
│ Synthesis Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Layer 0 │ │ Layer 1 │ │ Layer N │ │ Layer X │ │
│ │ (ICMP) │ │ (DNS) │ │ (HTTPS) │ │ (auto) │ │
│ │ Osc+Amp │ │ Osc+Amp │ │ Osc+Amp │ │ Osc+Amp │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┴────────────┴──────────────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ Mixer │ │
│ │ (sum+clip) │ │
│ └─────┬──────┘ │
└──────────────────────────┼──────────────────────────────────┘
│ PCM sample stream (float32[])
▼
┌─────────────────────────────────────────────────────────────┐
│ Encoding Layer │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ PCM Buffer Accumulator → LAME MP3 Encoder │ │
│ │ (go-lame / CGo libmp3lame) │ │
│ └──────────────────────┬──────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
│ .mp3 file
▼
Output File
Component Responsibilities
| Component | Responsibility | Typical Implementation |
|---|---|---|
| CLI Entry | Parse flags, wire all components, handle Ctrl+C via os.Signal |
main.go, cobra or flag package |
| PacketSource | Open interface via pcap/AF_PACKET, emit packets into channel | gopacket.PacketSource.Packets() → <-chan gopacket.Packet |
| Protocol Classifier | Inspect decoded layers (IP, TCP, UDP, ICMP, DNS); assign class label | Pure Go switch on packet.Layer() type assertions |
| Unknown Traffic Clusterer | Hash or bucket unclassified flows by port range / packet size signature; assign stable label ID | Simple feature-hash bucketer; no heavy ML needed for v1 |
| Time-Window Accumulator | Batch packets into N-ms windows; emit packet-count and byte-volume per class | ticker-driven goroutine, map accumulation |
| Sound Layer (per class) | Maintain a sine oscillator at a fixed root frequency; update amplitude from window snapshot | Oscillator struct with phase accumulator; amplitude lerp |
| Mixer | Sum all layer outputs sample-by-sample; clamp/normalize to [-1, 1] | Simple additive sum with soft clip |
| MP3 Encoder | Accept PCM float32 frames; encode to MP3 on flush/stop | go-lame (CGo) or pure-Go fallback |
| Output File | Write encoded bytes to disk path from CLI flag | os.File + buffered writer |
Recommended Project Structure
netsynth/
├── main.go # CLI wiring, signal handling, top-level orchestration
├── capture/
│ └── capture.go # PacketSource wrapper, interface open/close, chan Packet
├── classify/
│ ├── classifier.go # Protocol dispatch, class label assignment
│ └── cluster.go # Unknown traffic bucketer (feature hash)
├── aggregate/
│ └── window.go # Time-window accumulator, WindowSnapshot type
├── synth/
│ ├── oscillator.go # Phase-accumulator sine oscillator
│ ├── layer.go # Per-traffic-class sound layer (osc + amp target)
│ └── mixer.go # Sum layers → float32 PCM frames
├── encode/
│ └── mp3.go # PCM → MP3 via go-lame; file flush on close
└── config/
└── mapping.go # Protocol → frequency/harmonic assignment table
Structure Rationale
- capture/: Isolates pcap/root-privilege boundary. Everything above it operates on typed Go channels with no pcap dependency.
- classify/: Cleanly separates rule-based (known protocol) from heuristic (unknown cluster) logic. Each can be tested with synthetic packet fixtures independently.
- aggregate/: The only stateful time-domain component. Isolating it makes window size configurable without touching synthesis.
- synth/: Pure PCM math — no I/O, no pcap. Fully unit-testable with deterministic inputs. The mixer owns the sample rate constant.
- encode/: CGo boundary lives here and nowhere else. If LAME is replaced (e.g., pure Go encoder), only this package changes.
- config/: Static frequency-to-protocol table. Separating it avoids magic numbers scattered across synth/.
Architectural Patterns
Pattern 1: Channel-Connected Pipeline Stages
What: Each component is a goroutine that reads from an inbound channel and writes to an outbound channel. The done channel (closed on Ctrl+C) signals all stages to drain and exit cleanly.
When to use: Always — this is the idiomatic Go pipeline pattern described in the Go Blog.
Trade-offs: Slightly more setup than direct function calls; pays off immediately with clean shutdown and testability of individual stages.
Example:
// Each stage signature follows this pattern
func Classify(done <-chan struct{}, packets <-chan gopacket.Packet) <-chan ClassifiedPacket {
out := make(chan ClassifiedPacket, 256)
go func() {
defer close(out)
for {
select {
case <-done:
return
case pkt, ok := <-packets:
if !ok { return }
out <- classify(pkt)
}
}
}()
return out
}
Pattern 2: Ticker-Driven Window Flush
What: The aggregation goroutine owns a time.Ticker. On each tick it snapshots accumulated counters and sends a WindowSnapshot downstream, then resets counters.
When to use: Anywhere time-based batching converts a high-frequency stream into low-frequency control signals.
Trade-offs: Fixed window size (e.g. 500ms) is simple but loses sub-window dynamics. Sliding windows add complexity with marginal benefit for ambient synthesis.
Example:
func Aggregate(done <-chan struct{}, events <-chan ClassifiedPacket, windowMs int) <-chan WindowSnapshot {
out := make(chan WindowSnapshot, 8)
ticker := time.NewTicker(time.Duration(windowMs) * time.Millisecond)
go func() {
defer close(out)
counts := map[TrafficClass]int{}
for {
select {
case <-done:
return
case <-ticker.C:
out <- snapshot(counts)
counts = map[TrafficClass]int{}
case ev, ok := <-events:
if !ok { return }
counts[ev.Class]++
}
}
}()
return out
}
Pattern 3: Per-Layer Amplitude Lerp
What: Each sound layer holds a current amplitude and a target amplitude. On each audio frame the current value moves toward the target by a smoothing coefficient. The layer's oscillator always runs; silence is achieved by targeting amplitude = 0.
When to use: Whenever window snapshots drive synthesis — avoids clicks/pops from abrupt amplitude changes.
Trade-offs: Adds minimal CPU overhead (one multiply per frame per layer); necessary for perceptually smooth audio.
Data Flow
Primary Flow: Packets to PCM
Network Interface
│
▼ (gopacket pcap handle)
PacketSource.Packets() chan
│
▼ (classify goroutine)
ClassifiedPacket chan
│
▼ (aggregate goroutine, ticker)
WindowSnapshot chan ─────────────────────────────────┐
│
(synth goroutine,
per window snap:
update amplitude targets)
│
PCM frame generator loop
(renders N frames per window,
one frame = sum of all layers)
│
▼
PCM []float32 blocks
│
▼
LAME encoder (streaming)
│
▼
MP3 bytes → output file
Shutdown Flow
Ctrl+C → os.Signal → close(done) channel
│
├── capture goroutine: drain + close packet chan
├── classify goroutine: drain + close event chan
├── aggregate goroutine: drain + close snapshot chan
└── synth goroutine: flush remaining PCM → encoder.Flush() → file.Close()
Key Data Types
gopacket.Packet→ raw decoded packet from pcap; carries layer stack.ClassifiedPacket{Packet, Class TrafficClass, Bytes int}→ labeled event.WindowSnapshot{ClassCounts map[TrafficClass]int, ClassBytes map[TrafficClass]int}→ per-window aggregate; drives amplitude targets.[]float32PCM block → mixer output at 44100 Hz, mono; flows into LAME.
Build Order (Phase Implications)
Build in dependency order — each layer is independently testable before the next is added:
1. capture/ → can test: "does it open an interface and emit packets?"
2. classify/ → can test: "does ICMP get labeled ICMP?" (synthetic packets)
3. aggregate/ → can test: "does a 500ms window count correctly?"
4. synth/ → can test: "does mixer output expected amplitude?" (no pcap needed)
5. encode/ → can test: "does PCM produce valid MP3 bytes?"
6. main.go wiring → integration: full end-to-end pipeline
This ordering means:
- Phase 1 can deliver a working capture + classify pipeline writing JSON/text summaries — validating the hardest privilege/pcap risk early.
- Phase 2 delivers the synthesis engine in isolation — testable with synthetic
WindowSnapshotinputs before any real traffic. - Phase 3 wires them together with the MP3 encoder.
Anti-Patterns
Anti-Pattern 1: Synchronous Per-Packet Audio Rendering
What people do: Generate one audio sample or tone event per packet — a 10 Gbps link produces 14M packets/sec, making synchronous render impossible.
Why it's wrong: Breaks at any real traffic volume; produces click-heavy output, not smooth drone.
Do this instead: Batch packets into time windows (500ms–1s) and drive amplitude targets from the batch, not individual packets.
Anti-Pattern 2: Blocking Channel Sends in the Capture Path
What people do: Use unbuffered channels between PacketSource and classifier; slow classifier stalls the pcap ring buffer and causes kernel drops.
Why it's wrong: libpcap's kernel buffer is fixed-size; if userspace can't drain it fast enough, packets are silently dropped. For audio purposes this introduces silent gaps.
Do this instead: Use buffered channels (capacity 256–1024) between capture and classify. Drop packets on full buffer with a counter — acceptable for sonification, fatal to log completeness tools.
Anti-Pattern 3: CGo MP3 Encoding in the Hot Audio Loop
What people do: Call lame.Encode() synchronously inside the frame-render loop, stalling synthesis.
Why it's wrong: CGo calls carry overhead; libmp3lame may block on I/O; this disrupts the synthesis clock.
Do this instead: The synth goroutine pushes PCM blocks onto a buffered channel; a separate encoder goroutine drains and encodes. On shutdown, close the PCM channel and drain completely before lame.Close().
Anti-Pattern 4: Global Mutable State for Class Frequency Mapping
What people do: Use a global map[TrafficClass]float64 for frequency assignments modified at runtime.
Why it's wrong: Race conditions; hard to test; makes the mapping invisible to callers.
Do this instead: Pass the mapping table as an immutable struct at construction time. Auto-clustered classes append to a local slice protected by a mutex inside the clusterer — not a global.
Integration Points
External Services
| Dependency | Integration Pattern | Notes |
|---|---|---|
| libpcap / pcap.h | CGo via gopacket/pcap — requires libpcap-dev at build time | Can substitute AF_PACKET (linux only) to avoid CGo in capture; still needs root |
| libmp3lame | CGo via go-lame — requires libmp3lame-dev at build time | Binary distribution requires static linking or Docker; pure-Go MP3 (e.g. oto + gmp3) is an option but quality/speed tradeoff |
Internal Boundaries
| Boundary | Communication | Notes |
|---|---|---|
| capture ↔ classify | chan gopacket.Packet (buffered 512) |
classify must never block capture |
| classify ↔ aggregate | chan ClassifiedPacket (buffered 1024) |
aggregate is slower (ticker-driven); buffer absorbs bursts |
| aggregate ↔ synth | chan WindowSnapshot (buffered 4) |
synth consumes synchronously per window; small buffer is fine |
| synth ↔ encode | chan []float32 (buffered 8 blocks) |
encoder runs in separate goroutine to decouple CGo latency |
| all stages ↔ main | chan struct{} done channel |
closed on Ctrl+C; all stages select on it |
Scaling Considerations
This is a single-binary CLI tool, not a distributed service. Scaling concerns are throughput-based:
| Traffic Rate | Architecture Adjustments |
|---|---|
| Home/office (< 10K pps) | Default design handles easily with no tuning |
| Datacenter (100K–1M pps) | Increase capture buffer size; consider AF_PACKET with TPACKET_V3 ring buffer instead of pcap; classify goroutine may need fan-out to 2–4 workers |
| Line-rate 10G (> 5M pps) | Out of scope for v1 ambient audio tool — synthesis granularity at 500ms windows means exact packet-level accuracy is not required |
Scaling Priorities
- First bottleneck: Kernel pcap buffer drops — mitigated by buffered channels and accepting lossy capture (fine for sonification).
- Second bottleneck: CGo encoding latency coupling synthesis clock — mitigated by decoupled encoder goroutine.
Sources
- Go Pipeline patterns: Go Concurrency Patterns: Pipelines and cancellation — HIGH confidence, official Go blog
- SoNSTAR network sonification architecture: Sonification of Network Traffic Flow for Monitoring and Situational Awareness, arXiv 1712.07029 — MEDIUM confidence (abstract only accessed)
- gopacket channel API: gopacket pkg.go.dev — HIGH confidence, official package docs
- bleep synthesizer architecture (Go): GitHub bspaans/bleep — MEDIUM confidence (README inspection)
- Waveform synthesis PCM patterns in Go: Audio From Scratch With Go — Dylan Meeus — MEDIUM confidence
- go-lame MP3 encoding: go-lame pkg.go.dev — MEDIUM confidence
- Drone amplitude/frequency modulation patterns: Drone auralization model, Acta Acustica 2024 — MEDIUM confidence
Architecture research for: NetSynth — network-traffic-to-audio synthesis CLI (Go) Researched: 2026-03-24