chore: complete v1.1 milestone — Custom Sound Mappings
Archive roadmap and requirements to milestones/, update PROJECT.md with shipped state, collapse ROADMAP.md, update retrospective. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
+40
-23
@@ -2,7 +2,7 @@
|
||||
|
||||
## 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.
|
||||
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, offline pcap file sonification, and fully customizable sound mappings via TOML config.
|
||||
|
||||
## Core Value
|
||||
|
||||
@@ -10,17 +10,11 @@ Network traffic patterns are instantly recognizable as distinct sounds — a pin
|
||||
|
||||
## Current State
|
||||
|
||||
**v1.0 MVP shipped 2026-03-26.** 3,254 lines of Go across 6 packages.
|
||||
**v1.1 Custom Sound Mappings shipped 2026-03-26.** ~4,675 lines of Go across 7 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.
|
||||
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, BurntSushi/toml v1.6.0.
|
||||
|
||||
All 16 v1 requirements validated. Full pipeline working: capture -> classify -> aggregate -> synthesize -> MP3.
|
||||
|
||||
**Phase 5 complete 2026-03-26:** Waveform types (sine, square, sawtooth, triangle) with bandlimited synthesis added. OscillatorBank decoupled from global config — NewBank now accepts injected config maps with dynamic gain scaling.
|
||||
|
||||
**Phase 6 complete 2026-03-26:** TOML config system added. Users can override frequency and waveform per traffic class via `netsynth.toml` (auto-discovered or `--config` flag). Partial overrides, unknown-key validation, and fail-fast startup errors. New `config` package with BurntSushi/toml.
|
||||
|
||||
**Phase 7 complete 2026-03-26:** User-defined classification rules via `[[rules]]` TOML blocks with port/protocol/class fields. User rules prepend before built-ins (first-match-wins). Auto-frequency assignment (FNV-32a, 1200-2350 Hz) for new class names. `--print-config` flag outputs full effective config as commented TOML with source annotations.
|
||||
All 16 v1.0 requirements + 11 v1.1 requirements validated. Full pipeline with customizable sound mappings: capture -> classify -> aggregate -> synthesize -> MP3.
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -38,16 +32,28 @@ All 16 v1 requirements validated. Full pipeline working: capture -> classify ->
|
||||
- BPF capture filter for scoping live traffic
|
||||
- Offline pcap file sonification with timestamp-based windowing
|
||||
|
||||
### Validated (v1.1)
|
||||
|
||||
- TOML config file with partial override semantics (frequency, waveform per class)
|
||||
- Auto-discovery: `./netsynth.toml`, `~/.config/netsynth/config.toml`
|
||||
- `--config` flag for explicit config path (error if missing)
|
||||
- Unknown-key validation with clear error naming the typo'd key
|
||||
- Four waveform types: sine, square, sawtooth, triangle (bandlimited)
|
||||
- User-defined classification rules via `[[rules]]` TOML blocks
|
||||
- User rules prepend before built-ins (first-match-wins priority)
|
||||
- Auto-frequency assignment for custom class names (no silent gaps)
|
||||
- `--print-config` outputs effective config as commented TOML
|
||||
|
||||
### Active
|
||||
|
||||
(See REQUIREMENTS.md for v1.1 requirements)
|
||||
(No active requirements — next milestone not yet defined)
|
||||
|
||||
### 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
|
||||
- Stereo position configuration — add in future if requested
|
||||
|
||||
## Context
|
||||
|
||||
@@ -55,7 +61,8 @@ All 16 v1 requirements validated. Full pipeline working: capture -> classify ->
|
||||
- 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
|
||||
- 14 built-in traffic classes: 10 known protocols + 4 hash-bucketed unknowns (extensible via custom rules)
|
||||
- TOML config with partial overrides, unknown-key validation, auto-discovery
|
||||
|
||||
## Constraints
|
||||
|
||||
@@ -78,18 +85,28 @@ All 16 v1 requirements validated. Full pipeline working: capture -> classify ->
|
||||
| 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 |
|
||||
| BurntSushi/toml over manual parsing | Industry-standard Go TOML library, Undecoded() catches typos | Good |
|
||||
| Pointer fields for partial overrides | `*float64`, `*string` distinguish "not set" from zero values | Good |
|
||||
| Bandlimited additive synthesis | Prevents aliasing in square/sawtooth/triangle without FFT overhead | Good |
|
||||
| FNV-32a hash for auto-frequency | Deterministic, collision-resistant, maps to unused 1200-2350 Hz range | Good |
|
||||
| LoadResult struct over tuple return | Clean single return value, extensible for future fields | Good |
|
||||
| --print-config as flag (not subcommand) | Consistent with --list-interfaces pattern, simpler CLI surface | Good |
|
||||
|
||||
## Current Milestone: v1.1 Custom Sound Mappings
|
||||
## Shipped Milestones
|
||||
|
||||
**Goal:** Users can customize how traffic sounds via a TOML config file
|
||||
<details>
|
||||
<summary>v1.1 Custom Sound Mappings (shipped 2026-03-26)</summary>
|
||||
|
||||
**Target features:**
|
||||
- ~~Custom frequency per traffic class (override built-in Hz values)~~ Done (Phase 6)
|
||||
- ~~Custom waveform per class (sine, square, sawtooth, triangle)~~ Done (Phase 5-6)
|
||||
- ~~User-defined classification rules with custom sounds~~ Done (Phase 7)
|
||||
- ~~Auto-discover config from ./netsynth.toml or ~/.config/netsynth/config.toml~~ Done (Phase 6)
|
||||
- ~~--config flag for explicit config path~~ Done (Phase 6)
|
||||
- ~~--print-config to inspect effective config~~ Done (Phase 7)
|
||||
Users can customize how traffic sounds via a TOML config file — frequency, waveform, custom classification rules, and config inspection.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>v1.0 MVP (shipped 2026-03-26)</summary>
|
||||
|
||||
Full capture -> classify -> synthesize -> MP3 pipeline with 14 traffic classes, BPF filtering, and pcap sonification.
|
||||
|
||||
</details>
|
||||
|
||||
## Evolution
|
||||
|
||||
@@ -110,4 +127,4 @@ This document evolves at phase transitions and milestone boundaries.
|
||||
4. Update Context with current state
|
||||
|
||||
---
|
||||
*Last updated: 2026-03-26 after Phase 7 completion (v1.1 milestone — all phases complete)*
|
||||
*Last updated: 2026-03-26 after v1.1 milestone*
|
||||
|
||||
Reference in New Issue
Block a user