# Project Research Summary

**Project:** NetSynth v1.2 — Extended Protocol Coverage with Grouped Sound Families
**Domain:** Network traffic sonification CLI (Go) — packet capture to ambient MP3
**Researched:** 2026-03-27
**Confidence:** HIGH

## Executive Summary

NetSynth v1.2 extends an already-shipped Go CLI tool that captures live network traffic and synthesizes it into an ambient MP3 soundscape. The existing v1.1 codebase (~4,675 lines, 7 packages) provides a validated pipeline: go-pcap capture → port-based classification → EMA-smoothed additive synthesis → LAME MP3 encoding. The v1.2 milestone adds ~21 new protocol classes across 7 sound families (Mail, Remote Access, File Transfer, Infrastructure expansion, Database, Directory/Auth, VoIP), expanding from 14 total classes to ~35. No new external dependencies are required — every new protocol is detectable via the existing port-based Rule classifier, and group identity is expressed purely through frequency proximity and waveform consistency in `ClassFreqConfigs`.

The recommended approach is strictly additive: extend three locations in the codebase (`classify/types.go` for constants, `classify/rules.go` for port rules, `synth/config.go` for frequency configs) in a fixed order to keep tests green throughout. The highest-value protocols for v1.2 are the Tier 1 set (IMAP, POP3, FTP, SMB, RDP, mDNS, SSDP, SNMP, MySQL, PostgreSQL, Redis) because they appear on nearly every network type. The group-as-frequency-proximity design means family identity emerges from the audio itself — no new data structures are needed for the group concept beyond a `Group string` metadata field on `FreqConfig`.

The key risks are all backward-compatibility and perceptual-design concerns rather than engineering complexity. The critical risks are: (1) frequency rebalancing silently invalidating existing user TOML configs, (2) the `autoAssignFreq` range in `config.go` colliding with new built-in frequencies if not updated, and (3) within-family detuning that is psychoacoustically too narrow to be perceptually distinct. These are all preventable with explicit design choices made before any code is written. The milestone complexity is LOW — all changes are data additions to existing packages, and the build order is clear from the architecture research.

## Key Findings

### Recommended Stack

The v1.2 stack is identical to v1.1 — no new dependencies are required. All existing packages (gopacket/gopacket v1.5.0, packetcap/go-pcap, sjzar/go-lame v0.0.9, spf13/cobra v1.10.2, BurntSushi/toml v1.6.0) are validated and unchanged. The gopacket `layers` package has native decoders for SIP (LayerTypeSIP, id 133) and TLS (LayerTypeTLS, id 140) at v1.5.0, but port-based `Rule` matching is the correct and simpler approach for all v1.2 protocols — using native layer decoders would add code paths without classification benefit, since port numbers are unambiguous for every protocol in scope.

**Core technologies (unchanged from v1.1):**
- `gopacket/gopacket v1.5.0`: Packet capture and protocol layer decoding — community fork, actively maintained, Go 1.24+
- `packetcap/go-pcap`: Pure-Go live capture via mmap ring buffer — no CGo, Linux/macOS
- `sjzar/go-lame v0.0.9`: MP3 encoding with embedded LAME C source — no system library dependency
- `spf13/cobra v1.10.2`: CLI flags, signal handling, --help generation
- `BurntSushi/toml v1.6.0`: TOML config loading with strict unknown-key validation
- Hand-rolled additive synth + EMA: oscillators with bandlimited harmonics, exponential moving average amplitude smoothing per layer

### Expected Features

**Must have (table stakes for v1.2):**
- Mail family: IMAP/IMAPS (TCP 143, 993), POP3/POP3S (TCP 110, 995), SMTP submission (TCP 587, 465) — present on every office and home network
- Remote Access expansion: RDP (TCP 3389), VNC (TCP 5900), Telnet (TCP 23) — completes the SSH family
- File Transfer family: FTP (TCP 20, 21), SMB (TCP 445), TFTP (UDP 69) — ubiquitous on NAS and Windows networks
- Infrastructure expansion: mDNS (UDP 5353), SSDP (UDP 1900), SNMP (UDP 161/162), Syslog (UDP 514) — constant background on all LAN segments
- Database family: MySQL (TCP 3306), PostgreSQL (TCP 5432), Redis (TCP 6379), MongoDB (TCP 27017) — all currently land in other-TCP
- Frequency allocation into family bands (group concept expressed via Hz proximity, not a new data structure)
- AllClasses() and ClassFreqConfigs updated atomically — existing test `TestNumLayersMatchesAllClasses` enforces this invariant
- --print-config reflects all new classes, organized with group-header comments

**Should have (differentiators for v1.2):**
- Directory/Auth family: LDAP/LDAPS (TCP 389, 636), Kerberos (UDP/TCP 88) — every enterprise/Windows network
- VoIP family: SIP/SIP-TLS (UDP/TCP 5060, 5061) — IP phone traffic on office networks
- QUIC/HTTP3 class (UDP 443) — distinct from HTTPS on TCP 443; significant fraction of modern web traffic
- Within-family waveform consistency: protocols in a family share the same waveform type for timbral family identity
- Group-header section comments in --print-config output (cosmetic, high value for user discoverability)

**Defer (v2+):**
- Dynamic port protocols: RTP (negotiated ephemeral ports), FTP data channel — require stateful flow tracking across packets
- Deep packet inspection for application-layer classification — massive scope, no sonification benefit over port matching
- Collapsed "Mail" or "Database" class — loses per-protocol identity (can't distinguish IMAP inbound from SMTP outbound)
- MQTT, AMQP, Kafka, BGP, OSPF — IoT/routing protocols absent on general networks; niche
- Port-range rule support in the Rule struct — needed for RTP; valid v1.3 enhancement
- Runtime group concept as a data structure — groups emerge from frequency proximity; no struct needed in v1.2

### Architecture Approach

The v1.2 architecture is strictly additive to the existing pipeline: `config.Load` → `classify.NewClassifier` → `encode.RunSynthesis` → `synth.NewBank` → MP3. The only new concept is `Group string` on `FreqConfig` in the synth package — this metadata field is used only by `PrintConfig` for section headers and has zero effect on synthesis math. `bank.go`, `encode/mp3.go`, and `main.go` require no changes. Group identity is expressed architecturally through frequency proximity alone: protocols in the same family are assigned `BaseHz` values within a shared band, and within-band detuning of at least a major second interval (ratio 1.122) ensures psychoacoustic distinctness while maintaining timbral family coherence.

**Major components and their v1.2 changes:**
1. `classify/types.go` — new TrafficClass constants + AllClasses() extended in group-coherent order (additive)
2. `classify/rules.go` — new Rule entries before catch-alls for all new protocols; multi-port-to-single-class mapping for secure/insecure variants (additive; ordering is critical)
3. `synth/config.go` — Group field on FreqConfig; new ClassFreqConfigs entries; frequency rebalancing for family bands; NumLayers constant cleanup (highest-risk change due to backward compatibility)
4. `config/config.go` — optional group-header comments in PrintConfig (isolated to string output, no behavioral change)
5. `bank.go`, `encode/mp3.go`, `main.go` — no changes required

**Recommended build order (each step independently testable):**
1. Test and constant cleanup — remove stale NumLayers/GainPerLayer, update TestFrequenciesInRange bounds
2. Protocol list and frequency design (no code) — finalize all Hz values in family bands, check ERB constraints
3. New TrafficClass constants + AllClasses() in classify/types.go
4. New DefaultRules in classify/rules.go (depends on step 3)
5. Add Group field to FreqConfig — independent of steps 3/4
6. Add ClassFreqConfigs entries with finalized frequencies; update autoAssignFreq base
7. PrintConfig group-header comments (optional polish)

### Critical Pitfalls

1. **Frequency rebalancing silently invalidates v1.1 user TOML configs** — Users with explicit Hz overrides will retain stale v1.1 values after rebalancing; users without overrides hear unexplained soundscape changes. Prevention: assign all new protocols to frequency ranges above 1047 Hz (unoccupied by v1.1 built-ins), leaving the 65–1047 Hz existing layout frozen. If existing class frequencies must move, document every Hz change in release notes.

2. **autoAssignFreq range [1200, 2350] Hz collision with new built-ins** — If new built-in classes use frequencies in the 1200–2350 Hz auto-assign range, user-defined custom classes can hash to the same frequency silently. Prevention: push autoAssignFreq base above all built-in frequencies (e.g., 4500 Hz) after finalizing v1.2 ClassFreqConfigs. Add a compile-time test asserting no built-in falls in the auto-assign range.

3. **NumLayers/GainPerLayer exported constant is stale** — bank.go uses `1.0 / float64(len(cfgs))` dynamically; the exported `synth.GainPerLayer` constant is frozen at 14-layer value. Any new v1.2 code referencing `synth.GainPerLayer` will compute wrong gain. Prevention: remove or deprecate the constant before adding any new classes; bank.go's dynamic computation is the sole authoritative source.

4. **TestFrequenciesInRange hardcodes [60, 1100] Hz** — CI fails immediately when adding classes above 1100 Hz. Prevention: update the test bounds to the new valid range (e.g., [60, 4000]) before adding any ClassFreqConfigs entries outside the current range. This is a false blocker if not addressed first.

5. **Within-family detuning too narrow for psychoacoustic distinctness** — Fixed small Hz steps (e.g., 10 Hz) fall inside the critical band (ERB) at higher frequencies — at 1000 Hz ERB is ~72 Hz; at 2000 Hz it is ~117 Hz. Tones within the critical band merge perceptually. Prevention: use logarithmic interval separations — at minimum a major second (ratio 1.122). Verify all within-family pairs satisfy `|f2 - f1| > ERB(min(f1,f2))` before committing Hz values.

6. **Three-location atomic update required for each new class** — Adding a protocol requires updating AllClasses(), ClassFreqConfigs, and the TrafficClass constant. Missing any one causes test failures that are diagnostic but confusing. Prevention: update all three in the same commit, or introduce a single `builtinClassDefs` slice that drives both AllClasses() and validates ClassFreqConfigs.

7. **Secure/insecure protocol variants create frequency overcrowding if treated as separate classes** — SMTP:25, SMTP-submit:587, SMTPS:465 as three classes produces three frequencies where users want one "mail" sound. Prevention: map all ports of a protocol family to a single TrafficClass using multiple Rule entries. Port-to-class is many-to-one within a family.

## Implications for Roadmap

Based on the research, v1.2 should follow a 4-phase sequence driven by dependency order and the need to resolve design decisions before code decisions.

### Phase 1: Test and Constant Cleanup

**Rationale:** Three existing tests and one exported constant actively block v1.2 work if not addressed first. Cleaning these up prevents confusing CI failures throughout the milestone.
**Delivers:** Stale NumLayers/GainPerLayer constant removed or deprecated; TestFrequenciesInRange updated to accept new range; TestNumLayersMatchesAllClasses renamed and its invariant documented clearly.
**Addresses:** Pitfalls C3 (stale GainPerLayer), C4 (hardcoded range test blocking correct additions)
**Avoids:** Wasted debugging time on pre-existing issues presenting as new failures

### Phase 2: Protocol List and Frequency Design (No Code)

**Rationale:** The frequency allocation must be designed before any ClassFreqConfigs entries are written. Getting this wrong after the fact requires touching every entry. The autoAssignFreq collision and psychoacoustic ERB constraints must be resolved at design time.
**Delivers:** Final protocol class list (Tier 1 + Tier 2 from FEATURES.md, multi-port collapsed to single class per family), complete Hz allocation for all ~35 classes in family bands, autoAssignFreq base set above all built-ins, ERB check confirming all within-family pairs are perceptually distinct.
**Addresses:** Pitfalls C1 (backward compat), C2 (auto-assign collision), C6 (critical band masking), C7 (secure/insecure variant crowding)
**Avoids:** Frequency rebalancing causing retroactive rework; tone merging within families discovered only during listening tests

### Phase 3: Classification Layer

**Rationale:** New constants and rules must exist before synth entries can reference them. This phase is purely additive to the classify package with no audio impact — safe to land and test in isolation.
**Delivers:** All ~21 new TrafficClass constants, AllClasses() updated in family-grouped order, DefaultRules extended with new port rules (multi-port-to-single-class pattern applied per family).
**Addresses:** Protocol coverage table stakes (Mail, Remote Access, File Transfer, Infrastructure, Database, Directory/Auth, VoIP families from FEATURES.md)
**Avoids:** Pitfall C8 (three-location atomicity — enforced by existing test), Pitfall C9 (range-based protocols like RTP deferred)
**Uses:** Port-based Rule classification — same pattern as existing SSH/HTTP/DNS rules, no new code paths

### Phase 4: Synthesis and Config Layer

**Rationale:** ClassFreqConfigs entries depend on both the protocol list from Phase 2 design and the TrafficClass constants from Phase 3. The Group field on FreqConfig and PrintConfig group headers are the final polish on this phase.
**Delivers:** All new FreqConfig entries with finalized frequencies from Phase 2; Group field added to FreqConfig; autoAssignFreq base updated and compile-time range test added; optional PrintConfig group-header section comments.
**Addresses:** Table stakes (--print-config reflects new classes); differentiators (within-family tonal design, group headers)
**Avoids:** Pitfall C2 (confirmed by new compile-time test), Pitfall C5 (no new TOML top-level keys since groups are not user-configurable)
**Manual validation required:** A listening test with a real or synthetic pcap file is needed after this phase — automated tests cannot substitute for ear confirmation that family identity is perceptually clear.

### Phase Ordering Rationale

- Phase 1 before everything because pre-existing test blockers cause false CI failures throughout the milestone
- Phase 2 (design) before code because Hz allocation is the hardest-to-change decision with the broadest blast radius; fixing retroactively touches every ClassFreqConfigs entry
- Phase 3 before Phase 4 because TrafficClass constants must exist before ClassFreqConfigs can reference them
- Phase 4 is last because it depends on both the design (Phase 2) and the constants (Phase 3)

### Research Flags

Phases with well-documented patterns (no additional research needed):
- **Phase 1:** Straightforward constant and test cleanup; all relevant code is in the existing codebase
- **Phase 3:** Port rules follow the exact same pattern as existing SSH/HTTP/DNS rules; no new patterns or unknowns
- **Phase 4:** FreqConfig additions follow the exact same pattern as existing entries; the Group field is a non-functional metadata addition

Phases that require design validation:
- **Phase 2:** The frequency allocation should be validated with a listening test on a real pcap file before committing to final Hz values. The ERB computations are straightforward math; the perceptual result requires ear confirmation. This is inherent to audio design work.

## Confidence Assessment

| Area | Confidence | Notes |
|------|------------|-------|
| Stack | HIGH | Validated against shipped v1.1 codebase; no new dependencies; gopacket layer types confirmed via direct GitHub source inspection |
| Features | MEDIUM-HIGH | Protocol selection based on IANA port registry, nDPI taxonomy, Wireshark dissectors; real-world traffic frequency is inference, not measurement |
| Architecture | HIGH | Derived from direct inspection of shipped v1.1 code (~4,675 lines); all integration points identified with specific file references and build order |
| Pitfalls | HIGH | All critical pitfalls grounded in specific code locations (config.go merge(), bank.go gainPerLayer, synth/config_test.go assertions); audio masking values from Glasberg & Moore 1990 ERB model |

**Overall confidence: HIGH**

### Gaps to Address

- **Frequency allocation requires listening validation:** No automated test replaces ear-testing. Plan a listening session with a diverse pcap file after Phase 4 before declaring the milestone complete.
- **Protocol frequency on real networks:** Tier 1/2 ranking is based on typical network types, not measurement on the target user's actual network. mDNS and SSDP are prominent on home/office LANs but absent on cloud workloads. The catch-all classes handle unrecognized traffic regardless, so this is a coverage quality concern, not a correctness concern.
- **Rule schema for range-based protocols:** RTP and NetBIOS (multi-port, non-contiguous) are explicitly deferred. If desired in v1.3+, the Rule struct needs `DstPortMin/Max` fields — a known future gap, not a v1.2 concern.

## Sources

### Primary (HIGH confidence)
- `github.com/gopacket/gopacket/blob/master/layers/layertypes.go` — LayerTypeSIP (id 133), LayerTypeTLS (id 140) confirmed at v1.5.0
- `github.com/gopacket/gopacket/blob/master/layers/ports.go` — UDP/TCP port pre-registration confirmed; mDNS/SNMP/QUIC absent
- `github.com/gopacket/gopacket/tree/master/layers` — directory listing; no mdns.go, quic.go, snmp.go, ldap.go, smb.go, rdp.go
- Direct codebase inspection: `synth/config.go`, `synth/bank.go`, `classify/types.go`, `classify/rules.go`, `classify/classifier.go`, `config/config.go`, `encode/mp3.go`, `cmd/netsynth/main.go`
- Glasberg & Moore 1990 ERB model: `ERB(f) = 24.7 * (4.37 * f/1000 + 1)` — critical bandwidth values for all relevant frequencies

### Secondary (MEDIUM confidence)
- IANA Service Name and Transport Protocol Port Number Registry — authoritative port assignments for all new protocols
- nDPI Protocols List (ntop) — 450+ protocol taxonomy; 17-category grouping model as design precedent
- nDPI 5.0 Enhanced Traffic Fingerprinting blog post — category-based grouping confirmed as production approach
- SoNSTAR: Sonification of Network Traffic (Paul Vickers) — academic network sonification reference
- Sonification of network traffic flow (PLoS One 2018) — research on perceptually useful protocol groupings

### Tertiary (LOW confidence)
- Protocol prevalence on "typical" networks (home/office/server/cloud) — inferred from nDPI taxonomy and Wireshark dissector popularity; not empirically measured on target networks

---
*Research completed: 2026-03-27*
*Ready for roadmap: yes*