diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..c09e8b1 --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,78 @@ +# Requirements: NetSynth + +**Defined:** 2026-03-26 +**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.1 Requirements + +Requirements for custom sound mappings milestone. Each maps to roadmap phases. + +### Config Loading + +- [ ] **CFG-01**: User can create a TOML config file that overrides default sound mappings +- [ ] **CFG-02**: Tool auto-discovers config from `./netsynth.toml` or `~/.config/netsynth/config.toml` (silent if absent) +- [ ] **CFG-03**: User can specify an explicit config path via `--config` flag (error if file missing) +- [ ] **CFG-04**: User can override individual values without replicating the entire default config (partial override) +- [ ] **CFG-05**: Unknown keys in config file produce a clear error with the typo'd key name +- [ ] **CFG-06**: User can run `netsynth --print-config` to see the effective config as commented TOML + +### Waveforms + +- [ ] **WAVE-01**: User can set waveform type per traffic class (sine, square, sawtooth, triangle) +- [ ] **WAVE-02**: Non-sine waveforms use bandlimited additive synthesis (no aliasing artifacts) + +### Custom Rules + +- [ ] **RULE-01**: User can define custom classification rules in TOML (match by port and/or protocol, assign class name and sound) +- [ ] **RULE-02**: User-defined rules take priority over built-in rules (prepend before defaults) +- [ ] **RULE-03**: User-defined class names automatically get a synthesis layer (no silent gaps) + +## Future Requirements + +Deferred to later releases. + +### 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 + +### Distribution + +- **DIST-01**: Single static binary with no runtime dependencies + +## Out of Scope + +| Feature | Reason | +|---------|--------| +| Stereo position configuration | Keeps v1.1 scope focused; add in future if requested | +| Real-time audio playback | File output only — established v1.0 constraint | +| GUI config editor | CLI-only tool; TOML is human-editable | +| JSON/YAML config format | TOML chosen for readability; one format keeps it simple | +| Config hot-reload | Non-interactive tool; config read once at startup | + +## Traceability + +Which phases cover which requirements. Updated during roadmap creation. + +| Requirement | Phase | Status | +|-------------|-------|--------| +| CFG-01 | - | Pending | +| CFG-02 | - | Pending | +| CFG-03 | - | Pending | +| CFG-04 | - | Pending | +| CFG-05 | - | Pending | +| CFG-06 | - | Pending | +| WAVE-01 | - | Pending | +| WAVE-02 | - | Pending | +| RULE-01 | - | Pending | +| RULE-02 | - | Pending | +| RULE-03 | - | Pending | + +**Coverage:** +- v1.1 requirements: 11 total +- Mapped to phases: 0 +- Unmapped: 11 + +--- +*Requirements defined: 2026-03-26* +*Last updated: 2026-03-26 after initial definition*