gurix/yoloyolo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: complete v1.1 milestone — Custom Sound Mappings

Browse Source 
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:
gurix
2026-03-26 22:05:09 +01:00
co-authored by Claude Opus 4.6
parent 5391207b37
commit 415b30b431
8 changed files with 263 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/MILESTONES.md
+15
View File
@@ -1,5 +1,20 @@
# Milestones # Milestones
## v1.1 Custom Sound Mappings (Shipped: 2026-03-26)
**Phases completed:** 3 phases, 6 plans, 3 tasks
**Key accomplishments:**
- Four waveform types (sine, square, sawtooth, triangle) with bandlimited additive synthesis and decoupled bank injection
- TOML config system with auto-discovery, partial override semantics, unknown-key validation, and `--config` flag
- User-defined classification rules via `[[rules]]` TOML blocks — prepend before built-ins, first-match-wins
- Auto-frequency assignment (FNV-32a hash, 1200-2350 Hz) for custom class names with no sound config
- `--print-config` flag outputs full effective config as commented TOML with source annotations
- End-to-end config flow: TOML file -> config.Load() -> LoadResult -> synthesis pipeline
---
## v1.0 MVP (Shipped: 2026-03-26) ## v1.0 MVP (Shipped: 2026-03-26)
**Phases completed:** 4 phases, 11 plans, 9 tasks **Phases completed:** 4 phases, 11 plans, 9 tasks
.planning/PROJECT.md
+40 -23
View File
@@ -2,7 +2,7 @@
## What This Is ## 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 ## Core Value
@@ -10,17 +10,11 @@ Network traffic patterns are instantly recognizable as distinct sounds — a pin
## Current State ## 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. All 16 v1.0 requirements + 11 v1.1 requirements validated. Full pipeline with customizable sound mappings: 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.
## Requirements ## Requirements
@@ -38,16 +32,28 @@ All 16 v1 requirements validated. Full pipeline working: capture -> classify ->
- BPF capture filter for scoping live traffic - BPF capture filter for scoping live traffic
- Offline pcap file sonification with timestamp-based windowing - 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 ### Active
(See REQUIREMENTS.md for v1.1 requirements) (No active requirements — next milestone not yet defined)
### Out of Scope ### Out of Scope
- Real-time audio playback — file output only - Real-time audio playback — file output only
- GUI or web interface — CLI only - GUI or web interface — CLI only
- Rhythmic/percussive output — ambient/drone style 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 ## Context
@@ -55,7 +61,8 @@ All 16 v1 requirements validated. Full pipeline working: capture -> classify ->
- Packet capture requires root/CAP_NET_RAW on Linux - Packet capture requires root/CAP_NET_RAW on Linux
- Pure Go capture layer (no libpcap dependency) - Pure Go capture layer (no libpcap dependency)
- MP3 encoding embeds LAME C source (no system library needed) - 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 ## 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 | | 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 | | Ordered []Rule classifier over switch | Configurable, extensible, first-match-wins semantics | Good |
| 500ms window duration | Balances temporal resolution against snapshot frequency for synthesis | 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:** Users can customize how traffic sounds via a TOML config file — frequency, waveform, custom classification rules, and config inspection.
- ~~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) </details>
- ~~User-defined classification rules with custom sounds~~ Done (Phase 7)
- ~~Auto-discover config from ./netsynth.toml or ~/.config/netsynth/config.toml~~ Done (Phase 6) <details>
- ~~--config flag for explicit config path~~ Done (Phase 6) <summary>v1.0 MVP (shipped 2026-03-26)</summary>
- ~~--print-config to inspect effective config~~ Done (Phase 7)
Full capture -> classify -> synthesize -> MP3 pipeline with 14 traffic classes, BPF filtering, and pcap sonification.
</details>
## Evolution ## Evolution
@@ -110,4 +127,4 @@ This document evolves at phase transitions and milestone boundaries.
4. Update Context with current state 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*
.planning/RETROSPECTIVE.md
+44 -7
View File
@@ -37,12 +37,49 @@
- go-audio/wav was unnecessary — writing PCM bytes directly to LameWriter is simpler - go-audio/wav was unnecessary — writing PCM bytes directly to LameWriter is simpler
- Hash-bucketed unknowns (4 classes) are sufficient for audio distinction without k-means complexity - Hash-bucketed unknowns (4 classes) are sufficient for audio distinction without k-means complexity
## Milestone: v1.1 — Custom Sound Mappings
**Shipped:** 2026-03-26
**Phases:** 3 | **Plans:** 6 | **Timeline:** 1 day (2026-03-26)
**LOC:** ~4,675 Go (+1,421 from v1.0) | **Packages:** 7
### What Was Built
- Four waveform types (sine, square, sawtooth, triangle) with bandlimited additive synthesis
- TOML config system: auto-discovery, partial overrides, unknown-key validation, `--config` flag
- User-defined `[[rules]]` classification rules with first-match-wins prepend semantics
- Auto-frequency assignment (FNV-32a hash) for custom class names
- `--print-config` flag with commented TOML output and source annotations
- LoadResult struct pattern for clean config-to-pipeline data flow
### What Worked
- Incremental config extension: Phase 6 built the config package, Phase 7 extended it cleanly
- TDD plans (type: tdd in frontmatter) produced higher-quality code with fewer regressions
- FNV-32a frequency assignment was verified experimentally during research before planning
- Worktree isolation for parallel executor agents prevented merge conflicts
- Reusing existing patterns (Rule struct, NewClassifier injection, Cobra flag-on-root) kept code consistent
### What Was Inefficient
- SUMMARY.md one-liner extraction continued to be noisy — summary-extract needs improvement
- Phase 5 could potentially have been merged with Phase 6 (waveform + config together)
### Patterns Established
- LoadResult struct for multi-value config returns (extensible without breaking callers)
- Pointer fields (`*float64`, `*string`) for partial TOML override semantics
- FNV-32a hash for deterministic resource assignment from string keys
- Flag-on-root pattern for early-exit operations (--list-interfaces, --print-config)
- `addAutoFreqEntries()` pattern: fill gaps in config before merge
### Key Lessons
- BurntSushi/toml Undecoded() works with array-of-tables (verified experimentally)
- Manual string building beats TOML encoder when you need inline comments/annotations
- Config extension is smooth when the original Load() was designed with clean boundaries
## Cross-Milestone Trends ## Cross-Milestone Trends
| Metric | v1.0 | | Metric | v1.0 | v1.1 |
|--------|------| |--------|------|------|
| Phases | 4 | | Phases | 4 | 3 |
| Plans | 11 | | Plans | 11 | 6 |
| Days | 3 | | Days | 3 | 1 |
| LOC | 3,254 | | LOC | 3,254 | 4,675 |
| Avg plan duration | ~8 min | | Avg plan duration | ~8 min | ~5 min |
.planning/ROADMAP.md
+11 -55
View File
@@ -3,7 +3,7 @@
## Milestones ## Milestones
- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26) - **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26)
- **v1.1 Custom Sound Mappings** — Phases 5-7 (in progress) - **v1.1 Custom Sound Mappings** — Phases 5-7 (shipped 2026-03-26)
## Phases ## Phases
@@ -19,60 +19,16 @@ Full details: `.planning/milestones/v1.0-ROADMAP.md`
</details> </details>
### v1.1 Custom Sound Mappings (In Progress) <details>
<summary>v1.1 Custom Sound Mappings (Phases 5-7) — SHIPPED 2026-03-26</summary>
**Milestone Goal:** Users can customize how traffic sounds via a TOML config file — setting custom frequencies, waveform types, and their own classification rules with named sounds. - [x] **Phase 5: Waveform Types and Bank Decoupling** - 2/2 plans — completed 2026-03-26
- [x] **Phase 6: Config Package and Sound Overrides** - 2/2 plans — completed 2026-03-26
- [x] **Phase 7: Custom Rules and Print-Config** - 2/2 plans — completed 2026-03-26
- [x] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature (completed 2026-03-26) Full details: `.planning/milestones/v1.1-ROADMAP.md`
- [x] **Phase 6: Config Package and Sound Overrides** - TOML loading, auto-discovery, partial merge, and frequency/waveform overrides wired end-to-end (completed 2026-03-26)
- [x] **Phase 7: Custom Rules and Print-Config** - User-defined classification rules and --print-config UX (completed 2026-03-26)
## Phase Details </details>
### Phase 5: Waveform Types and Bank Decoupling
**Goal**: Four waveform types are available per traffic class, and the synthesis bank accepts an injected config map instead of reading global state
**Depends on**: Phase 4
**Requirements**: WAVE-01, WAVE-02
**Success Criteria** (what must be TRUE):
1. User can set a traffic class to square, sawtooth, or triangle waveform and hear a tonally distinct sound with no audible aliasing or buzzing artifacts
2. Sine waveform continues to produce the same output as v1.0 — no regression
3. The synthesis bank builds layers from a passed-in config map rather than a hardcoded class list
**Plans:** 2/2 plans complete
Plans:
- [x] 05-01-PLAN.md — Waveform types: WaveformType enum, WaveformPresetHarmonics, NewLayer resolution
- [x] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
### Phase 6: Config Package and Sound Overrides
**Goal**: Users can create a TOML config file to override frequency and waveform per traffic class, with auto-discovery, partial override semantics, and clear validation errors
**Depends on**: Phase 5
**Requirements**: CFG-01, CFG-02, CFG-03, CFG-04, CFG-05
**Success Criteria** (what must be TRUE):
1. User creates a `netsynth.toml` in the working directory with a custom Hz value and the tool uses that frequency for the specified class without touching other classes
2. User runs the tool with no flags in a directory without a config file — it starts silently (no warning about missing config)
3. User passes `--config /path/to/custom.toml` and the tool uses that file; if the file does not exist, the tool exits with a clear error before capture begins
4. User types `frequncy = 440` in their config file and the tool exits at startup with an error naming `frequncy` as an unrecognized key
5. User sets waveform for one class in TOML and leaves all other classes at their defaults — the unspecified classes are unchanged
**Plans:** 2/2 plans complete
Plans:
- [x] 06-01-PLAN.md — Config package: TOML load, validate, merge with TDD (config/config.go, config/config_test.go)
- [x] 06-02-PLAN.md — CLI wiring: --config flag, RunSynthesis signature change, main.go integration
### Phase 7: Custom Rules and Print-Config
**Goal**: Users can define their own traffic classification rules in TOML, assign custom sounds to them, and inspect the full effective config before capture begins
**Depends on**: Phase 6
**Requirements**: RULE-01, RULE-02, RULE-03, CFG-06
**Success Criteria** (what must be TRUE):
1. User adds a `[[rules]]` block in TOML matching a custom port/protocol combination and hears a distinct tone for that traffic in the output MP3
2. User-defined rules fire before built-in protocol rules — a custom rule for port 443 overrides the default HTTPS classification for packets on that port
3. A user-defined class name gets its own synthesis layer automatically — no silence or missing audio for traffic matched by a custom rule
4. User runs `netsynth --print-config` and sees the full effective config (defaults merged with their overrides) as commented TOML, without starting a capture
**Plans:** 2/2 plans complete
Plans:
- [x] 07-01-PLAN.md — Config extension: RawRule, LoadResult, rule validation, auto-freq assignment (TDD)
- [x] 07-02-PLAN.md — CLI wiring: --print-config flag, user rule prepend, PrintConfig output
## Progress ## Progress
@@ -82,6 +38,6 @@ Plans:
| 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 | | 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 |
| 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 | | 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 |
| 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 | | 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 |
| 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 | | 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 |
| 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 | | 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 |
| 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 | | 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 |
.planning/STATE.md
+7 -7
View File
@@ -2,9 +2,9 @@
gsd_state_version: 1.0 gsd_state_version: 1.0
milestone: v1.1 milestone: v1.1
milestone_name: Custom Sound Mappings milestone_name: Custom Sound Mappings
status: executing status: milestone_complete
stopped_at: Completed 07-02-PLAN.md stopped_at: v1.1 milestone shipped
last_updated: "2026-03-26T20:55:57.847Z" last_updated: "2026-03-26T21:02:36.710Z"
last_activity: 2026-03-26 last_activity: 2026-03-26
progress: progress:
total_phases: 3 total_phases: 3
@@ -21,13 +21,13 @@ progress:
See: .planning/PROJECT.md (updated 2026-03-26) See: .planning/PROJECT.md (updated 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. **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.
**Current focus:** Phase 07 — custom-rules-and-print-config **Current focus:** Planning next milestone
## Current Position ## Current Position
Phase: 07 Phase: All v1.1 phases complete
Plan: Not started Plan: N/A
Status: Ready to execute Status: Milestone v1.1 shipped — ready for next milestone
Last activity: 2026-03-26 Last activity: 2026-03-26
Progress: [░░░░░░░░░░] 0% Progress: [░░░░░░░░░░] 0%
.planning/REQUIREMENTS.md → .planning/milestones/v1.1-REQUIREMENTS.md
+9
View File
@@ -1,3 +1,12 @@
# Requirements Archive: v1.1 Custom Sound Mappings
**Archived:** 2026-03-26
**Status:** SHIPPED
For current requirements, see `.planning/REQUIREMENTS.md`.
---
# Requirements: NetSynth # Requirements: NetSynth
**Defined:** 2026-03-26 **Defined:** 2026-03-26
.planning/milestones/v1.1-ROADMAP.md
+87
View File
@@ -0,0 +1,87 @@
# Roadmap: NetSynth
## Milestones
- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-26)
- **v1.1 Custom Sound Mappings** — Phases 5-7 (in progress)
## Phases
<details>
<summary>v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-26</summary>
- [x] **Phase 1: Capture and Classification** - 4/4 plans — completed 2026-03-25
- [x] **Phase 2: Audio Synthesis Engine** - 3/3 plans — completed 2026-03-26
- [x] **Phase 3: Pipeline Integration and MVP** - 2/2 plans — completed 2026-03-26
- [x] **Phase 4: Power User Features** - 2/2 plans — completed 2026-03-26
Full details: `.planning/milestones/v1.0-ROADMAP.md`
</details>
### v1.1 Custom Sound Mappings (In Progress)
**Milestone Goal:** Users can customize how traffic sounds via a TOML config file — setting custom frequencies, waveform types, and their own classification rules with named sounds.
- [x] **Phase 5: Waveform Types and Bank Decoupling** - Internal refactors establishing waveform enum and injectable bank signature (completed 2026-03-26)
- [x] **Phase 6: Config Package and Sound Overrides** - TOML loading, auto-discovery, partial merge, and frequency/waveform overrides wired end-to-end (completed 2026-03-26)
- [x] **Phase 7: Custom Rules and Print-Config** - User-defined classification rules and --print-config UX (completed 2026-03-26)
## Phase Details
### Phase 5: Waveform Types and Bank Decoupling
**Goal**: Four waveform types are available per traffic class, and the synthesis bank accepts an injected config map instead of reading global state
**Depends on**: Phase 4
**Requirements**: WAVE-01, WAVE-02
**Success Criteria** (what must be TRUE):
1. User can set a traffic class to square, sawtooth, or triangle waveform and hear a tonally distinct sound with no audible aliasing or buzzing artifacts
2. Sine waveform continues to produce the same output as v1.0 — no regression
3. The synthesis bank builds layers from a passed-in config map rather than a hardcoded class list
**Plans:** 2/2 plans complete
Plans:
- [x] 05-01-PLAN.md — Waveform types: WaveformType enum, WaveformPresetHarmonics, NewLayer resolution
- [x] 05-02-PLAN.md — Bank decoupling: NewBank injected config map, dynamic GainPerLayer, test updates
### Phase 6: Config Package and Sound Overrides
**Goal**: Users can create a TOML config file to override frequency and waveform per traffic class, with auto-discovery, partial override semantics, and clear validation errors
**Depends on**: Phase 5
**Requirements**: CFG-01, CFG-02, CFG-03, CFG-04, CFG-05
**Success Criteria** (what must be TRUE):
1. User creates a `netsynth.toml` in the working directory with a custom Hz value and the tool uses that frequency for the specified class without touching other classes
2. User runs the tool with no flags in a directory without a config file — it starts silently (no warning about missing config)
3. User passes `--config /path/to/custom.toml` and the tool uses that file; if the file does not exist, the tool exits with a clear error before capture begins
4. User types `frequncy = 440` in their config file and the tool exits at startup with an error naming `frequncy` as an unrecognized key
5. User sets waveform for one class in TOML and leaves all other classes at their defaults — the unspecified classes are unchanged
**Plans:** 2/2 plans complete
Plans:
- [x] 06-01-PLAN.md — Config package: TOML load, validate, merge with TDD (config/config.go, config/config_test.go)
- [x] 06-02-PLAN.md — CLI wiring: --config flag, RunSynthesis signature change, main.go integration
### Phase 7: Custom Rules and Print-Config
**Goal**: Users can define their own traffic classification rules in TOML, assign custom sounds to them, and inspect the full effective config before capture begins
**Depends on**: Phase 6
**Requirements**: RULE-01, RULE-02, RULE-03, CFG-06
**Success Criteria** (what must be TRUE):
1. User adds a `[[rules]]` block in TOML matching a custom port/protocol combination and hears a distinct tone for that traffic in the output MP3
2. User-defined rules fire before built-in protocol rules — a custom rule for port 443 overrides the default HTTPS classification for packets on that port
3. A user-defined class name gets its own synthesis layer automatically — no silence or missing audio for traffic matched by a custom rule
4. User runs `netsynth --print-config` and sees the full effective config (defaults merged with their overrides) as commented TOML, without starting a capture
**Plans:** 2/2 plans complete
Plans:
- [x] 07-01-PLAN.md — Config extension: RawRule, LoadResult, rule validation, auto-freq assignment (TDD)
- [x] 07-02-PLAN.md — CLI wiring: --print-config flag, user rule prepend, PrintConfig output
## Progress
| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Capture and Classification | v1.0 | 4/4 | Complete | 2026-03-25 |
| 2. Audio Synthesis Engine | v1.0 | 3/3 | Complete | 2026-03-26 |
| 3. Pipeline Integration and MVP | v1.0 | 2/2 | Complete | 2026-03-26 |
| 4. Power User Features | v1.0 | 2/2 | Complete | 2026-03-26 |
| 5. Waveform Types and Bank Decoupling | v1.1 | 2/2 | Complete | 2026-03-26 |
| 6. Config Package and Sound Overrides | v1.1 | 2/2 | Complete | 2026-03-26 |
| 7. Custom Rules and Print-Config | v1.1 | 2/2 | Complete | 2026-03-26 |
README.md
+50 -2
View File
@@ -22,6 +22,9 @@ sudo netsynth -i eth0 --filter "port 53" -o dns.mp3
# Use a custom sound config # Use a custom sound config
sudo netsynth -i eth0 --config my-sounds.toml sudo netsynth -i eth0 --config my-sounds.toml
# Print effective config as a starting template
netsynth --print-config > my-sounds.toml
``` ```
## Installation ## Installation
@@ -71,6 +74,7 @@ netsynth [flags]
| `-o`, `--output` | Output MP3 file path (default: `netsynth-<timestamp>.mp3`) | | `-o`, `--output` | Output MP3 file path (default: `netsynth-<timestamp>.mp3`) |
| `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) | | `--filter` | BPF filter expression, tcpdump syntax (e.g. `"port 53"`) |
| `--config` | Path to a TOML config file for custom sound mappings | | `--config` | Path to a TOML config file for custom sound mappings |
| `--print-config` | Print the full effective config as commented TOML and exit |
| `--verbose` | Print per-window protocol activity to stderr | | `--verbose` | Print per-window protocol activity to stderr |
| `--list-interfaces` | List available network interfaces and exit | | `--list-interfaces` | List available network interfaces and exit |
@@ -91,11 +95,14 @@ netsynth --read traffic.pcap --filter "udp" -o udp-only.mp3
# Use a custom sound config # Use a custom sound config
sudo netsynth -i eth0 --config ~/my-sounds.toml sudo netsynth -i eth0 --config ~/my-sounds.toml
# Print the full effective config (great for creating a template)
netsynth --print-config > my-sounds.toml
``` ```
## Custom Sound Configuration ## Custom Sound Configuration
NetSynth supports TOML config files to override the default sound mappings per traffic class. You can change the frequency and waveform for any class without affecting the others. NetSynth supports TOML config files to override the default sound mappings per traffic class. You can change the frequency and waveform for any class, define your own classification rules, and inspect the effective config — all without affecting defaults you don't touch.
### Config File Discovery ### Config File Discovery
@@ -139,6 +146,47 @@ waveform = "square"
All waveforms use bandlimited additive synthesis to prevent aliasing artifacts. All waveforms use bandlimited additive synthesis to prevent aliasing artifacts.
### Custom Classification Rules
Define your own traffic classification rules using `[[rules]]` blocks. User-defined rules fire before built-in rules (first-match-wins):
```toml
# Match internal API traffic on port 8080
[[rules]]
protocol = "tcp"
port = 8080
class = "InternalAPI"
# Match all UDP traffic (port omitted = match any)
[[rules]]
protocol = "udp"
class = "AllUDP"
# Optionally customize the sound for your custom class
[sounds.InternalAPI]
frequency = 1500.0
waveform = "sawtooth"
```
Custom classes that don't have a `[sounds.*]` entry automatically get a unique frequency in the 1200-2350 Hz range.
### Print Config
Inspect the full effective configuration (defaults merged with your overrides):
```bash
# Print defaults (useful as a starting template)
netsynth --print-config
# Print with your overrides applied
netsynth --config my-sounds.toml --print-config
# Save as a template to edit
netsynth --print-config > template.toml
```
The output includes `(default)`, `(override)`, and `(auto-assigned)` annotations so you can see what's customized.
### Validation ### Validation
- **Unknown keys** are rejected at startup with an error naming the bad key (catches typos like `frequncy`) - **Unknown keys** are rejected at startup with an error naming the bad key (catches typos like `frequncy`)
@@ -155,7 +203,7 @@ Capture -> Classify -> Aggregate -> Synthesize -> MP3
1. **Capture** — Packets are read from a live interface (via [go-pcap](https://github.com/packetcap/go-pcap)) or a pcap file. Optional BPF filtering reduces the stream to traffic of interest. 1. **Capture** — Packets are read from a live interface (via [go-pcap](https://github.com/packetcap/go-pcap)) or a pcap file. Optional BPF filtering reduces the stream to traffic of interest.
2. **Classify** — Each packet is matched against 12 protocol rules (ICMP, DNS, HTTPS, SSH, HTTP, SMTP, NTP, DHCP, etc.). Unrecognized traffic is deterministically hash-bucketed into 4 "unknown" classes so it still produces distinct sounds. 2. **Classify** — Each packet is matched against protocol rules (ICMP, DNS, HTTPS, SSH, HTTP, SMTP, NTP, DHCP, etc.) plus any user-defined rules from the config file. User rules fire first. Unrecognized traffic is deterministically hash-bucketed into 4 "unknown" classes so it still produces distinct sounds.
3. **Aggregate** — Classified packets are grouped into 500ms time windows. Each window records per-protocol packet counts that drive synthesis amplitudes. 3. **Aggregate** — Classified packets are grouped into 500ms time windows. Each window records per-protocol packet counts that drive synthesis amplitudes.