yoloyolo/.planning/research/FEATURES.md

# Feature Research

**Domain:** Network traffic sonification CLI tool (packet capture → ambient MP3)
**Researched:** 2026-03-24
**Confidence:** MEDIUM — this is a niche domain; most comparable tools are research prototypes or GUI applications, not CLI tools. Table stakes are derived from tcpdump/packet-capture CLI conventions and sonification research literature.

---

## Feature Landscape

### Table Stakes (Users Expect These)

Features users assume exist. Missing these = product feels incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Network interface selection (`-i eth0`) | tcpdump/tshark convention; every capture tool has this | LOW | `gopacket` exposes interface list; needs `--list-interfaces` companion flag |
| Output file path flag (`-o output.mp3`) | Any file-producing CLI must let you name the output | LOW | Sensible default (e.g. `netsynth-<timestamp>.mp3`) reduces friction |
| Graceful Ctrl+C capture stop with file save | Users expect the tool to cleanly finalize the MP3 on interrupt | MEDIUM | Need signal handler; partial synthesis must be flushed to encoder before exit |
| Per-protocol sound distinction | Core value prop: ping sounds different from HTTPS noise | MEDIUM | Minimum recognizable set: ICMP, DNS, TCP (port 443), TCP (other), UDP |
| Packet count / traffic summary on exit | Every capture tool prints capture statistics; users want to know what was heard | LOW | Print to stderr so it doesn't interfere with stdout pipeline use |
| Privilege error message | `pcap` silently fails or panics without root/CAP_NET_RAW; users need a clear message | LOW | Detect EACCES / EPERM on open; print actionable message (`sudo` or capability hint) |
| List available interfaces (`--list-interfaces`) | Users don't know interface names on unfamiliar machines | LOW | Wrap `pcap.FindAllDevs()`; print name + description |
| Minimum viable duration guard | Zero-packet capture should not produce a corrupt/empty MP3 | LOW | Check sample count before encoding; exit with clear error if nothing was captured |

### Differentiators (Competitive Advantage)

Features that set the product apart. Not required, but valuable.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Auto-clustering of unrecognized traffic | Unknown traffic still gets a unique voice instead of being silently dropped — honest audio fingerprint | HIGH | Requires unsupervised clustering (e.g. flow-feature vector → k-means or simple hash bucketing); each cluster gets a deterministic frequency mapping |
| Ambient/drone style output (layered sine harmonics) | Distinct from event-ping tools (Peep, SoNSTAR); slow tonal evolution makes long captures listenable | HIGH | Synthesize per-protocol drone layers; amplitude driven by time-windowed packet rate; mix layers before encoding |
| Time-windowed amplitude evolution | Traffic volume changes over time are reflected in the audio; the mix evolves rather than being static | MEDIUM | Segment capture into N-second windows; compute per-layer gain per window; apply smooth gain ramps between windows |
| Configurable time window duration (`--window 10`) | Lets users tune responsiveness vs. smoothness; research tools (SoNSTAR) expose this parameter | LOW | Default 10s; range 1–60s is sensible |
| BPF capture filter support (`--filter "tcp port 443"`) | Power users want to scope what gets sonified; tcpdump BPF syntax is universally known | MEDIUM | Pass expression directly to `gopacket`/`pcap`; validate at startup before capture begins |
| Offline pcap file input (`--read capture.pcap`) | Lets users sonify historical captures, not just live traffic; useful for analysis and demos | MEDIUM | Replace live capture source with `pcap.OpenOffline()`; time-compress or time-expand to fixed output duration |
| Verbose protocol activity log to stderr (`--verbose`) | Developers and curious users want to see what was classified | LOW | Print per-window protocol breakdown table to stderr during capture |
| Configurable output duration when reading pcap file (`--duration 30`) | Offline pcap may span hours; need ability to compress to a target audio length | LOW | Only meaningful with `--read`; scale time windows proportionally |
| Single static binary (`go build`) | Eliminates dependency hell on target machines | LOW (build-time) | Go native; no CGo for MP3 encoding avoids runtime `.so` requirements — choose a pure-Go MP3 encoder |

### Anti-Features (Commonly Requested, Often Problematic)

Features that seem good but create problems.

| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| Real-time audio playback (speakers while capturing) | Feels more immediate; Peep and dmeldrum6/Network-Sonification do this | Requires platform audio APIs (ALSA/CoreAudio/WASAPI), cross-platform complexity triples; conflicts with file-output simplicity; latency/buffering bugs; CGo or external library dependency | File output only; user can pipe MP3 to `mpv`/`afplay` themselves after capture |
| GUI or web dashboard | Visually richer; existing tools like Network-Sonification are GUI-first | Negates single-binary CLI value; doubles scope; Go GUI toolkits are immature or require CGo | Emit stderr text summary; let external tools consume the MP3 |
| Custom sound mapping configuration file | Power-user request; SoNSTAR supports per-user sound uploads | Configuration surface area is large; predefined + auto-cluster covers the use case adequately for v1; config files introduce parsing/validation work | Well-chosen defaults + auto-cluster for unknowns; defer custom mapping to v2 |
| Rhythmic/percussive output mode | Some sonification tools use discrete note triggers per packet | Ambient/drone style is the deliberate differentiator; per-packet triggers at high traffic volumes produce noise, not information | Stick to amplitude-modulated harmonic drones; volume changes carry the rhythm implicitly |
| Deep-packet inspection / payload parsing | Users might want to hear HTTP body content, TLS handshake details | Requires reassembly, encryption handling, legal concerns about payload interception; massive complexity | Classify by header fields only (port, protocol, flags, packet size); that is sufficient for the audio fingerprint goal |
| Streaming MP3 output (write while capturing) | Real-time preview of what's being synthesized | MP3 frame boundaries and VBR headers require the full file to be finalized; streaming output would produce a non-standard file | Write to temp buffer during capture, finalize and flush on Ctrl+C |
| Anomaly detection / alerting | Natural extension once you have classified traffic | Adds a monitoring-tool responsibility on top of the audio-fingerprint responsibility; these are different user jobs | Stick to "produce an audio fingerprint"; anomaly detection is a separate tool |

---

## Feature Dependencies

```
[Interface selection / list-interfaces]
    └──required-by──> [Live capture]

[Live capture] ──OR── [Offline pcap input]
    └──required-by──> [Protocol classification]
                          └──required-by──> [Auto-clustering of unknowns]
                          └──required-by──> [Per-protocol drone layer synthesis]
                                                └──required-by──> [Time-windowed amplitude evolution]
                                                                      └──required-by──> [Layer mixing]
                                                                                            └──required-by──> [MP3 encoding & file output]

[BPF capture filter] ──enhances──> [Live capture]
[Configurable time window] ──tunes──> [Time-windowed amplitude evolution]
[Offline pcap + --duration] ──requires──> [Offline pcap input]
[Verbose flag] ──enhances──> [Protocol classification] (reporting only, no data dependency)
[Graceful Ctrl+C] ──requires──> [MP3 encoding & file output] (must flush before exit)
```

### Dependency Notes

- **Protocol classification requires Live capture OR Offline pcap:** These are the two data sources; everything downstream is source-agnostic.
- **Time-windowed amplitude evolution requires Protocol classification:** You need classified packet counts per window before you can derive per-layer gain values.
- **MP3 encoding requires Layer mixing:** You cannot encode until all layers for a time window are mixed to a PCM buffer.
- **Graceful Ctrl+C requires MP3 encoding:** The signal handler must trigger the encode-and-flush path, not just `os.Exit`.
- **Auto-clustering enhances Protocol classification:** It extends classification to traffic that doesn't match predefined rules; the audio pipeline treats cluster-assigned tones identically to predefined protocol tones.
- **BPF filter conflicts with Offline pcap input (partial):** `pcap` supports BPF on offline files, so this works technically, but user expectation for offline mode is usually "sonify all traffic in the file" — document the interaction clearly.

---

## MVP Definition

### Launch With (v1)

Minimum viable product — what's needed to validate the concept.

- [ ] Network interface selection (`-i`) and `--list-interfaces` — required for capture
- [ ] Live packet capture with Ctrl+C stop — core interaction model
- [ ] Protocol classification: ICMP, DNS, TCP/443, TCP/other, UDP — minimum set for a recognizable fingerprint
- [ ] Auto-clustering of unrecognized traffic (simple hash-bucketing by port/proto is acceptable for v1) — honest representation of full traffic
- [ ] Per-protocol ambient drone layer synthesis (sine harmonics, amplitude modulated by packet rate) — core differentiator
- [ ] Time-windowed amplitude evolution (10s default) — makes the output dynamic
- [ ] MP3 encoding and file output with sensible default filename — deliverable artifact
- [ ] Capture statistics summary on exit (stderr) — basic UX courtesy
- [ ] Privilege error detection and clear message — prevents silent failure

### Add After Validation (v1.x)

Features to add once core is working.

- [ ] BPF capture filter (`--filter`) — add when users report wanting to scope captures
- [ ] Offline pcap file input (`--read`) — add when users want to sonify historical captures
- [ ] Verbose protocol activity log (`--verbose`) — add when debugging/demo use cases emerge
- [ ] Configurable time window duration (`--window`) — add if users report default feels too slow or too fast
- [ ] Configurable output duration for pcap input (`--duration`) — depends on offline input being implemented

### Future Consideration (v2+)

Features to defer until product-market fit is established.

- [ ] Custom sound mapping configuration — defer; needs user research on what customization actually matters
- [ ] Improved clustering algorithm (k-means on flow features vs. simple hash) — defer until users report clusters feel meaningless
- [ ] Multi-interface capture — defer; adds complexity to packet deduplication

---

## Feature Prioritization Matrix

| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Interface selection + list-interfaces | HIGH | LOW | P1 |
| Live capture with Ctrl+C stop | HIGH | LOW | P1 |
| Protocol classification (ICMP, DNS, TCP, UDP) | HIGH | MEDIUM | P1 |
| Ambient drone synthesis (per-protocol layers) | HIGH | HIGH | P1 |
| Time-windowed amplitude evolution | HIGH | MEDIUM | P1 |
| MP3 encoding + file output | HIGH | MEDIUM | P1 |
| Capture stats on exit | MEDIUM | LOW | P1 |
| Privilege error message | MEDIUM | LOW | P1 |
| Auto-clustering of unknown traffic | MEDIUM | MEDIUM | P1 |
| BPF capture filter | MEDIUM | MEDIUM | P2 |
| Offline pcap file input | MEDIUM | MEDIUM | P2 |
| Verbose flag | LOW | LOW | P2 |
| Configurable time window | LOW | LOW | P2 |
| Custom sound mapping | LOW | HIGH | P3 |
| Real-time playback | LOW | HIGH | P3 (anti-feature, avoid) |

**Priority key:**
- P1: Must have for launch
- P2: Should have, add when possible
- P3: Nice to have, future consideration

---

## Competitor Feature Analysis

| Feature | SoNSTAR (Python, research) | Network-Sonification (C#, Windows GUI) | Peep (C, Unix, 2000) | NetSynth (our approach) |
|---------|----------------------------|-----------------------------------------|----------------------|------------------------|
| Interface selection | Interactive prompt | GUI dropdown | Config file | CLI flag `-i` |
| Protocol coverage | TCP flag states | TCP, UDP, HTTP, HTTPS, DNS, ICMP | Any syslog-able event | ICMP, DNS, TCP, UDP + auto-cluster |
| Sound style | Recorded natural sounds (forest ambience) | Waveform shapes per protocol (sine/square/triangle) | Discrete event sounds | Synthesized harmonic drones |
| Output | Real-time audio (Max/MSP) | Real-time audio (WPF) | Real-time audio (Unix audio) | MP3 file |
| Time aggregation | Configurable window (default 20s) | Per-packet event | Per-event | Configurable window (default 10s) |
| CLI/scriptable | Partial (Python prompts) | No (GUI only) | Yes (daemon) | Yes (single binary, flags) |
| Offline pcap input | No | No | No | v1.x |
| Auto-clustering | No | No | No | Yes (v1 hash-bucket) |
| Single binary | No | No | No | Yes (Go) |
| Open source | Yes | Yes | Yes | Intended |

---

## Sources

- [SoNSTAR: Sonification of Networks for SiTuational AwaReness — Paul Vickers](https://paulvickers.github.io/SoNSTAR/)
- [Sonification of network traffic flow for monitoring and situational awareness — PLOS One](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0195948)
- [SoNSTAR GitHub repository — nuson/SoNSTAR](https://github.com/nuson/SoNSTAR)
- [Network-Sonification GitHub — dmeldrum6/Network-Sonification](https://github.com/dmeldrum6/Network-Sonification)
- [Peep (The Network Auralizer): Monitoring Your Network With Sound — USENIX 2000](https://www.usenix.org/legacyurl/peep-network-auralizer-monitoring-your-network-sound)
- [Sonification of DDoS Attacks — Imperva](https://www.imperva.com/blog/archive/sonification-of-ddos-attacks/)
- [Data Sonification Toolkit — Sound and data parameters](https://www.sonificationkit.com/data-sonification/concepts/sound-and-data-parameters)
- [tcpdump man page — tcpdump.org](https://www.tcpdump.org/manpages/tcpdump.1.html)
- [The Sound of Data: A gentle introduction to sonification — Programming Historian](https://programminghistorian.org/en/lessons/sonification)

---
*Feature research for: network traffic sonification CLI (NetSynth)*
*Researched: 2026-03-24*