From 4e4bc6ce0fbcbf4fe306a7c90a7070ccaf9600f5 Mon Sep 17 00:00:00 2001
From: Markus Graf <info@markusgraf.ch>
Date: Tue, 24 Mar 2026 22:41:08 +0100
Subject: [PATCH] docs: define v1 requirements

---
 .planning/REQUIREMENTS.md | 93 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 .planning/REQUIREMENTS.md

diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md
new file mode 100644
index 0000000..6df1ad9
--- /dev/null
+++ b/.planning/REQUIREMENTS.md
@@ -0,0 +1,93 @@
+# Requirements: NetSynth
+
+**Defined:** 2026-03-24
+**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.
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Packet Capture
+
+- [ ] **CAPT-01**: User can specify network interface via `-i` flag
+- [ ] **CAPT-02**: User can list available network interfaces via `--list-interfaces`
+- [ ] **CAPT-03**: Capture runs until user presses Ctrl+C, then gracefully flushes and saves MP3
+- [ ] **CAPT-04**: User sees a clear actionable error message when lacking capture privileges (sudo/CAP_NET_RAW hint)
+- [ ] **CAPT-05**: User can filter captured traffic using BPF syntax via `--filter` flag
+- [ ] **CAPT-06**: User can sonify a pcap file instead of live traffic via `--read` flag
+
+### Traffic Classification
+
+- [ ] **CLAS-01**: Known protocols (ICMP, DNS, TCP/443, TCP/other, UDP, SSH) each produce a distinct recognizable sound
+- [ ] **CLAS-02**: Unrecognized traffic is auto-clustered and assigned unique tones automatically
+- [ ] **CLAS-03**: On exit, user sees a summary of packet counts and protocol breakdown (printed to stderr)
+- [ ] **CLAS-04**: User can enable per-window protocol activity log via `--verbose` flag
+
+### Audio Synthesis
+
+- [ ] **SYNTH-01**: Each traffic class generates a distinct ambient/drone layer (layered sine/harmonic waves)
+- [ ] **SYNTH-02**: Drone layer amplitudes evolve over time windows based on traffic volume per class
+- [ ] **SYNTH-03**: Multiple drone layers are mixed into a single coherent audio stream without distortion
+
+### Output
+
+- [ ] **OUT-01**: User can specify output file path via `-o` flag (defaults to `netsynth-<timestamp>.mp3`)
+- [ ] **OUT-02**: Output is encoded as a valid MP3 file
+- [ ] **OUT-03**: Empty captures (zero packets) produce a clear error instead of a corrupt file
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Audio Tuning
+
+- **TUNE-01**: User can configure time window duration via `--window` flag
+- **TUNE-02**: User can configure output duration when reading pcap files via `--duration` flag
+- **TUNE-03**: User can customize sound mappings via configuration file
+
+### Distribution
+
+- **DIST-01**: Single static binary with no runtime dependencies
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Real-time audio playback | Platform audio API complexity triples scope; users can pipe MP3 to mpv/afplay |
+| GUI or web dashboard | Negates single-binary CLI value; doubles scope |
+| Rhythmic/percussive output | Ambient/drone is the deliberate differentiator |
+| Deep packet inspection | Massive complexity; header-level classification sufficient for audio fingerprint |
+| Anomaly detection/alerting | Different user job; stick to audio fingerprint |
+| Streaming MP3 output | MP3 VBR headers require finalization; buffer-then-encode is correct |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| CAPT-01 | — | Pending |
+| CAPT-02 | — | Pending |
+| CAPT-03 | — | Pending |
+| CAPT-04 | — | Pending |
+| CAPT-05 | — | Pending |
+| CAPT-06 | — | Pending |
+| CLAS-01 | — | Pending |
+| CLAS-02 | — | Pending |
+| CLAS-03 | — | Pending |
+| CLAS-04 | — | Pending |
+| SYNTH-01 | — | Pending |
+| SYNTH-02 | — | Pending |
+| SYNTH-03 | — | Pending |
+| OUT-01 | — | Pending |
+| OUT-02 | — | Pending |
+| OUT-03 | — | Pending |
+
+**Coverage:**
+- v1 requirements: 16 total
+- Mapped to phases: 0
+- Unmapped: 16 ⚠️
+
+---
+*Requirements defined: 2026-03-24*
+*Last updated: 2026-03-24 after initial definition*