# Stack Research

**Domain:** Go CLI tool — network packet capture, traffic classification, audio synthesis, MP3 encoding
**Researched:** 2026-03-24
**Confidence:** MEDIUM-HIGH (packet capture and CLI: HIGH; audio synthesis in Go: MEDIUM; MP3 encoding: MEDIUM)

---

## Recommended Stack

### Core Technologies

| Technology | Version | Purpose | Why Recommended |
|------------|---------|---------|-----------------|
| `github.com/gopacket/gopacket` | v1.5.0 | Packet capture, protocol decoding | The canonical Go packet library. Community fork (`gopacket/gopacket`) supersedes the original Google repo (`google/gopacket`) as of 2024; released v1.5.0 in November 2025, minimum Go 1.24. 14.5k dependents; has ICMP, TCP, UDP, DNS, TLS layer decoders built in. |
| `github.com/packetcap/go-pcap` | v0.0.0-20251215 | Pure-Go live packet capture backend | Replaces CGo libpcap dependency for live capture. 100% native Go, Linux + macOS, mmap-based kernel ring buffer for performance. Implements the `gopacket.PacketDataSource` interface so gopacket decodes packets on top of it. Enables CGO_ENABLED=0 builds and cross-compilation. |
| `github.com/sjzar/go-lame` | v0.0.9 | MP3 encoding | Embeds libmp3lame C source directly via CGo — no external `libmp3lame` system package required. Published April 2025. Exposes sample rate, channels, quality control. Produces LAME-quality MP3, unlike the pure-Go shine-mp3 port which produces larger, lower-quality output. Tradeoff: requires CGo, so `CGO_ENABLED=1` and a C compiler at build time. |
| `github.com/spf13/cobra` | v1.10.2 | CLI flag parsing and command structure | The industry standard for Go CLIs (Kubernetes, Docker, Hugo, etc.). v1.10.2 released December 2025. Handles `--interface`, `--output` flags, Ctrl+C signal plumbing, and `--help` generation automatically. No alternatives worth considering for this scope. |

### Supporting Libraries

| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| `github.com/muesli/kmeans` | v0.3.1 | K-means clustering for unrecognized traffic patterns | Use to auto-cluster packets that don't match known protocol rules. Feed feature vectors: [port, protocol_num, packet_size_bin, direction]. Last release July 2022 but mathematically stable; the algorithm doesn't change. Alternatively, implement a simple incremental classifier directly (see Architecture notes below). |
| `github.com/go-audio/wav` | latest | WAV file I/O as intermediate format | Use to write synthesized PCM as WAV before MP3 encoding pass. "Battle tested" per maintainer. Simplifies the PCM → encoder pipeline: synthesize float64 samples → write WAV → re-read as PCM → LAME encode. |
| `golang.org/x/sys/unix` | stdlib | Raw socket / CAP_NET_RAW privilege checks | Use for detecting if the process has required privileges and for signaling (SIGINT for clean shutdown). Part of Go extended stdlib — no external version pinning needed. |

### Development Tools

| Tool | Purpose | Notes |
|------|---------|-------|
| `go build -ldflags="-s -w"` | Stripped binary production builds | Reduces binary size significantly; combine with `upx` if size is critical |
| `goreleaser` | Cross-platform release builds | Handles CGo cross-compilation complexity with Docker-based build matrix; useful for distributing Linux x86_64 + ARM64 binaries |
| `golangci-lint` | Static analysis | Catches nil pointer dereferences common in packet-handling code |
| Wireshark / `tcpdump` | Manual verification of packet capture | Essential for confirming gopacket is decoding the right protocols before plugging into audio synthesis |

---

## Installation

```bash
# Initialize module
go mod init netsynth

# Core dependencies
go get github.com/gopacket/gopacket@v1.5.0
go get github.com/packetcap/go-pcap@latest
go get github.com/sjzar/go-lame@v0.0.9
go get github.com/spf13/cobra@v1.10.2

# Supporting
go get github.com/muesli/kmeans@v0.3.1
go get github.com/go-audio/wav@latest

# Build (CGo required for go-lame)
CGO_ENABLED=1 go build -ldflags="-s -w" -o netsynth ./cmd/netsynth
```

**Root/privilege requirement at runtime (not build time):**
```bash
sudo ./netsynth --interface eth0 --output traffic.mp3
# OR: grant capability instead of running as root
sudo setcap cap_net_raw+ep ./netsynth
```

---

## Alternatives Considered

| Recommended | Alternative | When to Use Alternative |
|-------------|-------------|-------------------------|
| `gopacket/gopacket` (community fork) | `google/gopacket` (original) | Never for new projects — original repo has 270 open issues, community fork actively merges fixes |
| `packetcap/go-pcap` (pure Go) | `gopacket/pcap` (CGo + libpcap) | Use libpcap path only if you need advanced BPF filter syntax or BSD/Windows support — it requires `libpcap-dev` system package |
| `sjzar/go-lame` (embedded C source) | `braheezy/shine-mp3` (pure Go) | Use shine-mp3 if CGo is truly impossible (e.g., WASM target) — but accept that output quality and file size are worse |
| `sjzar/go-lame` (embedded C source) | `viert/go-lame` (dynamic link) | Never — viert/go-lame requires libmp3lame installed on the target system, defeating single-binary distribution |
| Hand-rolled additive synthesis | `dasa.cc/snd`, `bspaans/bleep` | Use a library only if you need MIDI scheduling or real-time playback; for file output, the synthesis math is simple enough to own directly (see Architecture notes) |
| `muesli/kmeans` | `mpraski/clusters` | Use mpraski if you need online (incremental) clustering — it supports add-one-point updates vs muesli's batch-only approach |

---

## What NOT to Use

| Avoid | Why | Use Instead |
|-------|-----|-------------|
| `google/gopacket` (original) | Effectively unmaintained since 2022; 270 open issues, PRs not merged | `github.com/gopacket/gopacket` (community fork, v1.5.0) |
| `viert/go-lame` or `sunicy/go-lame` | Dynamic-links against system `libmp3lame` — breaks single-binary distribution, fails on machines without the library | `github.com/sjzar/go-lame` (embeds C source statically) |
| `braheezy/shine-mp3` (pure Go MP3) | Last commit 2023, explicitly not production-ready per its own README, produces larger lower-quality files, no bitrate control | `sjzar/go-lame` for quality, or WAV output if you must avoid CGo |
| `go-audio/generator` | **Archived February 2026, read-only** — do not take a new dependency on it | Write your own oscillator (20 lines of Go) or use `dasa.cc/snd` |
| `faiface/beep` | Designed for real-time audio playback via PortAudio/oto; pulls in platform audio drivers that are irrelevant for file output | Roll a minimal additive synthesizer directly (see below) |
| `dasa.cc/snd` | Plays audio through hardware; brings in real-time audio scheduling complexity unnecessary for batch file output | Roll a minimal additive synthesizer directly |
| urfave/cli | Fine for simpler tools, but Cobra's flag validation, help generation, and signal handling are better for a tool with multiple flags and clean shutdown semantics | `github.com/spf13/cobra` |

---

## Stack Patterns by Variant

**If CGo is acceptable (recommended path):**
- Use `sjzar/go-lame` for real MP3 quality
- Use `packetcap/go-pcap` for the capture layer (pure Go on Linux/macOS)
- Build with `CGO_ENABLED=1`; single binary is still self-contained because LAME C source is embedded

**If pure Go / no CGo is required (e.g., restricted build environment):**
- Use `braheezy/shine-mp3` for MP3 — accept lower quality and larger files
- Use `packetcap/go-pcap` for capture — already pure Go
- Build with `CGO_ENABLED=0`; truly static binary

**If Linux-only deployment is acceptable:**
- Consider `packetcap/go-pcap`'s mmap ring buffer mode for high-traffic interfaces (default on Linux)
- Privilege: `CAP_NET_RAW` setcap is cleaner than running as root

**For the audio synthesis layer — roll your own, don't use a library:**
The ambient/drone requirement is additive synthesis: N sine wave oscillators, each with a frequency and time-varying amplitude. This is 30-50 lines of Go:
```go
// Conceptual — not a library call
for t := 0; t < numSamples; t++ {
    sample := 0.0
    for _, layer := range layers {
        sample += layer.Amplitude(t) * math.Sin(2*math.Pi*layer.Freq*float64(t)/sampleRate)
    }
    pcm[t] = int16(sample * 32767)
}
```
No library adds value here. Libraries designed for real-time playback add complexity (audio thread management, ring buffers, OS audio drivers) that hurts a batch file-output tool.

---

## Version Compatibility

| Package | Compatible With | Notes |
|---------|-----------------|-------|
| `gopacket/gopacket@v1.5.0` | Go 1.24+ | v1.5.0 bumped minimum Go to 1.24; use Go 1.24.x toolchain |
| `packetcap/go-pcap` | Linux, macOS (Darwin) | No Windows support; this is acceptable per project constraints |
| `sjzar/go-lame@v0.0.9` | Any Go + C compiler; CGO_ENABLED=1 | Embeds LAME C source; no system library dependency |
| `spf13/cobra@v1.10.2` | Go 1.20+ | No issues with Go 1.24 |
| `muesli/kmeans@v0.3.1` | Go 1.12+ | Stable; no compatibility concerns |

---

## Audio Synthesis Architecture Note

Do not reach for an audio library. The synthesis requirement is:
1. Map each traffic class (ICMP, DNS, HTTPS, SSH, unknown-cluster-N) to a base frequency
2. Accumulate packet counts per class per time window (e.g., 500ms buckets)
3. Drive oscillator amplitude from smoothed packet rate (exponential moving average)
4. Sum N oscillators into PCM samples at 44100 Hz, 16-bit, mono
5. Write PCM to WAV via `go-audio/wav`, then encode WAV to MP3 via `sjzar/go-lame`

The WAV intermediate step decouples synthesis from encoding and gives you a debug artifact. Total synthesis code: ~100 lines. No external library needed.

---

## Sources

- `github.com/gopacket/gopacket` releases page — v1.5.0 confirmed, November 2025
- `pkg.go.dev/github.com/packetcap/go-pcap` — v0.0.0-20251215, pure Go, Linux/macOS confirmed
- `pkg.go.dev/github.com/sjzar/go-lame` — v0.0.9, April 2025, embedded C source confirmed
- `pkg.go.dev/github.com/spf13/cobra` — v1.10.2, December 2025
- `github.com/go-audio/generator` — archived February 2026 (read-only), do not use
- `braheezy.github.io/posts/what-i-learned-about-mp3-encoding/` — author's first-hand account of Go MP3 encoding options, concluded shine-mp3 is not production-grade
- `github.com/google/gopacket/issues/1016` — maintenance status discussion confirming community fork is preferred
- WebSearch: muesli/kmeans v0.3.1 last release July 2022 — LOW confidence on ongoing maintenance, but algorithm is stable
- WebSearch: cobra v1.9.1/v1.10.2 — MEDIUM confidence, confirmed via pkg.go.dev

---
*Stack research for: NetSynth — Go CLI network-traffic-to-audio tool*
*Researched: 2026-03-24*