311 lines
13 KiB
Markdown
311 lines
13 KiB
Markdown
---
|
|
phase: 02-audio-synthesis-engine
|
|
plan: 03
|
|
type: execute
|
|
wave: 3
|
|
depends_on: ["02-02"]
|
|
files_modified:
|
|
- encode/mp3.go
|
|
- encode/mp3_test.go
|
|
- cmd/netsynth/main.go
|
|
autonomous: true
|
|
requirements: [OUT-01, OUT-02, OUT-03]
|
|
|
|
must_haves:
|
|
truths:
|
|
- "Synthetic WindowSnapshots produce a valid MP3 file that passes ffprobe validation"
|
|
- "Zero-packet input produces a clear error message and no file on disk"
|
|
- "User can specify -o flag for output path; default includes timestamp"
|
|
- "MP3 is encoded at 44100 Hz, 128 kbps, stereo via go-lame"
|
|
artifacts:
|
|
- path: "encode/mp3.go"
|
|
provides: "EncodeMP3 function and RunSynthesis orchestrator"
|
|
contains: "func EncodeMP3"
|
|
- path: "encode/mp3_test.go"
|
|
provides: "Integration test with ffprobe validation and zero-packet guard test"
|
|
contains: "TestMP3Valid"
|
|
- path: "cmd/netsynth/main.go"
|
|
provides: "-o flag wiring with timestamp default, snapshot slice accumulator stub"
|
|
contains: "outputPath"
|
|
key_links:
|
|
- from: "encode/mp3.go"
|
|
to: "synth/bank.go"
|
|
via: "RunSynthesis calls bank.RenderWindow for each snapshot"
|
|
pattern: "bank\\.RenderWindow"
|
|
- from: "encode/mp3.go"
|
|
to: "synth/mixer.go"
|
|
via: "Uses StereoFramesToInt16Bytes for PCM conversion"
|
|
pattern: "StereoFramesToInt16Bytes"
|
|
- from: "cmd/netsynth/main.go"
|
|
to: "encode/mp3.go"
|
|
via: "Will wire RunSynthesis in Phase 3; -o flag defined now"
|
|
pattern: "outputPath"
|
|
---
|
|
|
|
<objective>
|
|
Build the MP3 encoder package and wire the -o output flag into the CLI. This completes OUT-01 (output path flag), OUT-02 (valid MP3 encoding), and OUT-03 (zero-packet guard). An integration test synthesizes from synthetic snapshots and validates the MP3 with ffprobe.
|
|
|
|
Purpose: The encoder is the final stage of the audio pipeline. After this plan, the complete synthesis chain (WindowSnapshot -> OscillatorBank -> stereo PCM -> MP3 file) is validated end-to-end against synthetic data.
|
|
|
|
Output: `encode/mp3.go`, `encode/mp3_test.go`, updated `cmd/netsynth/main.go` with -o flag.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
|
|
@$HOME/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/phases/02-audio-synthesis-engine/02-CONTEXT.md
|
|
@.planning/phases/02-audio-synthesis-engine/02-RESEARCH.md
|
|
@.planning/phases/02-audio-synthesis-engine/02-01-SUMMARY.md
|
|
@.planning/phases/02-audio-synthesis-engine/02-02-SUMMARY.md
|
|
|
|
@classify/types.go
|
|
@cmd/netsynth/main.go
|
|
|
|
<interfaces>
|
|
<!-- From synth/bank.go (created in Plan 02) -->
|
|
From synth/bank.go:
|
|
```go
|
|
func NewBank(tau float64) *OscillatorBank
|
|
func (b *OscillatorBank) RenderWindow(snap classify.WindowSnapshot) [][2]float64
|
|
```
|
|
|
|
From synth/mixer.go:
|
|
```go
|
|
func StereoFramesToInt16Bytes(frames [][2]float64) []byte
|
|
```
|
|
|
|
From synth/config.go:
|
|
```go
|
|
const SampleRate = 44100
|
|
const SamplesPerWindow = 22050
|
|
```
|
|
|
|
From classify/types.go:
|
|
```go
|
|
type WindowSnapshot struct {
|
|
Counts map[TrafficClass]int64
|
|
TotalPackets int64
|
|
WindowIndex int
|
|
}
|
|
```
|
|
|
|
<!-- From go-lame (external dependency) -->
|
|
From github.com/sjzar/go-lame:
|
|
```go
|
|
func NewWriter(w io.Writer) *LameWriter
|
|
wr.Encoder.SetInSamplerate(int)
|
|
wr.Encoder.SetOutSamplerate(int)
|
|
wr.Encoder.SetNumChannels(int)
|
|
wr.Encoder.SetBitrate(int)
|
|
wr.Encoder.SetQuality(int)
|
|
wr.Encoder.InitParams() // MUST call after all Set* and before Write
|
|
wr.Write([]byte) (int, error)
|
|
wr.Close() error
|
|
```
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto" tdd="true">
|
|
<name>Task 1: MP3 encoder package with zero-packet guard and integration test</name>
|
|
<files>encode/mp3.go, encode/mp3_test.go</files>
|
|
<read_first>
|
|
- synth/bank.go (NewBank, RenderWindow signatures)
|
|
- synth/mixer.go (StereoFramesToInt16Bytes)
|
|
- synth/config.go (SampleRate constant)
|
|
- classify/types.go (WindowSnapshot, TrafficClass)
|
|
- .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (Pattern 4: go-lame API, zero-packet guard, anti-patterns)
|
|
- .planning/phases/02-audio-synthesis-engine/02-CONTEXT.md (D-14: 128 kbps, D-16: zero-packet error)
|
|
</read_first>
|
|
<behavior>
|
|
- TestMP3Valid: Create 3 synthetic WindowSnapshots with varied traffic (ICMP=50, DNS=30 in snap1; HTTPS=200 in snap2; SSH=10, HTTP=80 in snap3). Run RunSynthesis into a temp file. Assert: file exists, file size > 0, `ffprobe -v error -show_entries format=format_name,duration,nb_streams -of csv=p=0 <file>` outputs "mp3" in format_name, duration > 0, nb_streams=1.
|
|
- TestZeroPacketError: Pass empty slice of snapshots (or snapshots where all TotalPackets=0). Assert: returns non-nil error containing "no packets", output file does NOT exist on disk.
|
|
- TestEncodeMP3DirectBytes: Call EncodeMP3 with known [][2]float64 frames (e.g., 44100 frames of 440Hz sine). Assert: output file > 0 bytes, ffprobe validates it as MP3.
|
|
</behavior>
|
|
<action>
|
|
**encode/mp3.go** — MP3 encoding and synthesis orchestrator:
|
|
|
|
```go
|
|
package encode
|
|
|
|
import (
|
|
"fmt"
|
|
"os"
|
|
|
|
lame "github.com/sjzar/go-lame"
|
|
|
|
"github.com/netsynth/netsynth/classify"
|
|
"github.com/netsynth/netsynth/synth"
|
|
)
|
|
|
|
// EncodeMP3 writes stereo PCM frames to an MP3 file at the given path.
|
|
// sampleRate=44100, bitrate=128 kbps, stereo, quality=5. Per D-13, D-14.
|
|
// CRITICAL: InitParams() must be called after all Set* calls (Pitfall 1).
|
|
func EncodeMP3(outputPath string, frames [][2]float64, sampleRate int) error {
|
|
f, err := os.Create(outputPath)
|
|
if err != nil {
|
|
return fmt.Errorf("create output file: %w", err)
|
|
}
|
|
defer f.Close()
|
|
|
|
wr := lame.NewWriter(f)
|
|
wr.Encoder.SetInSamplerate(sampleRate)
|
|
wr.Encoder.SetOutSamplerate(sampleRate)
|
|
wr.Encoder.SetNumChannels(2)
|
|
wr.Encoder.SetBitrate(128)
|
|
wr.Encoder.SetQuality(5)
|
|
wr.Encoder.InitParams() // MUST be after all Set* calls
|
|
|
|
pcmBytes := synth.StereoFramesToInt16Bytes(frames)
|
|
if _, err := wr.Write(pcmBytes); err != nil {
|
|
return fmt.Errorf("write PCM to LAME encoder: %w", err)
|
|
}
|
|
if err := wr.Close(); err != nil {
|
|
return fmt.Errorf("finalize MP3: %w", err)
|
|
}
|
|
return nil
|
|
}
|
|
|
|
// RunSynthesis consumes a slice of WindowSnapshots, renders audio via OscillatorBank,
|
|
// and encodes to MP3 at outputPath. Returns error if zero packets were captured (D-16/OUT-03).
|
|
// NOTE: Accepts a slice, not a channel — caller collects snapshots before calling this.
|
|
// The zero-packet check MUST happen before file creation (Pitfall 5).
|
|
func RunSynthesis(snapshots []classify.WindowSnapshot, outputPath string) error {
|
|
// D-16 / OUT-03: Zero-packet guard — check BEFORE creating output file
|
|
var totalPackets int64
|
|
for _, snap := range snapshots {
|
|
totalPackets += snap.TotalPackets
|
|
}
|
|
if totalPackets == 0 {
|
|
return fmt.Errorf("no packets captured: output MP3 not written (empty capture produces no audio)")
|
|
}
|
|
|
|
// Render all windows to stereo frames
|
|
bank := synth.NewBank(1.0) // tau=1.0s per D-07
|
|
var allFrames [][2]float64
|
|
for _, snap := range snapshots {
|
|
frames := bank.RenderWindow(snap)
|
|
allFrames = append(allFrames, frames...)
|
|
}
|
|
|
|
// Encode to MP3
|
|
return EncodeMP3(outputPath, allFrames, synth.SampleRate)
|
|
}
|
|
```
|
|
|
|
Key design:
|
|
- `RunSynthesis` takes a `[]classify.WindowSnapshot` slice (not a channel). The caller (main.go in Phase 3) collects from the channel, then passes the slice. This enables the zero-packet check before file creation.
|
|
- `EncodeMP3` is a separate function so it can be tested independently with raw frames.
|
|
- PCM bytes are written in a single `Write` call (batch output, not streaming — per project constraints).
|
|
|
|
Write tests FIRST, using `os.CreateTemp` for output files and `exec.Command("ffprobe", ...)` for validation. Clean up temp files in test teardown.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/dev/workspace/yoloyolo && CGO_ENABLED=1 go test ./encode/... -v -count=1</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- encode/mp3.go contains `func EncodeMP3(outputPath string, frames [][2]float64, sampleRate int) error`
|
|
- encode/mp3.go contains `func RunSynthesis(snapshots []classify.WindowSnapshot, outputPath string) error`
|
|
- encode/mp3.go contains `wr.Encoder.InitParams()` AFTER all `Set*` calls
|
|
- encode/mp3.go contains `if totalPackets == 0` guard BEFORE `os.Create`
|
|
- encode/mp3.go contains the error string "no packets captured"
|
|
- encode/mp3.go imports `github.com/sjzar/go-lame`
|
|
- encode/mp3_test.go contains `TestMP3Valid`
|
|
- encode/mp3_test.go contains `TestZeroPacketError`
|
|
- encode/mp3_test.go uses `ffprobe` to validate MP3 output
|
|
- `CGO_ENABLED=1 go test ./encode/...` exits 0
|
|
</acceptance_criteria>
|
|
<done>EncodeMP3 produces a valid MP3 file validated by ffprobe. RunSynthesis renders synthetic snapshots through the full pipeline. Zero-packet input returns error without creating a file. All encode tests pass.</done>
|
|
</task>
|
|
|
|
<task type="auto">
|
|
<name>Task 2: Wire -o output flag and snapshot accumulator stub into CLI</name>
|
|
<files>cmd/netsynth/main.go</files>
|
|
<read_first>
|
|
- cmd/netsynth/main.go (current Cobra flag setup, run function)
|
|
- .planning/phases/02-audio-synthesis-engine/02-CONTEXT.md (D-15: -o flag, timestamp default)
|
|
- .planning/phases/02-audio-synthesis-engine/02-RESEARCH.md (output flag wiring example)
|
|
</read_first>
|
|
<action>
|
|
Add the `-o` / `--output` flag to main.go. Per D-15: defaults to `netsynth-<timestamp>.mp3` when omitted. The flag is defined now but NOT wired to the synthesis pipeline yet — that happens in Phase 3 when capture and synthesis are integrated.
|
|
|
|
1. Add a package-level var:
|
|
```go
|
|
var outputPath string
|
|
```
|
|
|
|
2. Add the flag registration in `main()` after the existing flags:
|
|
```go
|
|
rootCmd.Flags().StringVarP(&outputPath, "output", "o", "", "Output MP3 file path (default: netsynth-<timestamp>.mp3)")
|
|
```
|
|
|
|
3. Add the timestamp default resolution at the top of `run()`, after the `--list-interfaces` check and before the interface check:
|
|
```go
|
|
// Resolve default output path (D-15 / OUT-01)
|
|
if outputPath == "" {
|
|
outputPath = fmt.Sprintf("netsynth-%s.mp3", time.Now().Format("20060102-150405"))
|
|
}
|
|
```
|
|
|
|
4. Add `"time"` to the imports.
|
|
|
|
5. Add a snapshot slice accumulator alongside the existing snapshot consumption loop, and a TODO for Phase 3 wiring. Replace the current `for snap := range snapshots` block to also collect snapshots into a slice:
|
|
```go
|
|
// Accumulate snapshots for synthesis (Phase 3 will pass to encode.RunSynthesis)
|
|
var collectedSnapshots []classify.WindowSnapshot
|
|
for snap := range snapshots {
|
|
collectedSnapshots = append(collectedSnapshots, snap)
|
|
aggregate.AccumulateTotals(totals, snap)
|
|
}
|
|
|
|
// TODO(phase-3): Pass collectedSnapshots to encode.RunSynthesis(collectedSnapshots, outputPath)
|
|
```
|
|
|
|
Do NOT import the encode package yet — Phase 3 handles that. The flag must be functional (parseable, shows in --help) even though the synthesis pipeline isn't wired.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/dev/workspace/yoloyolo && go build -o /dev/null ./cmd/netsynth/ && go run ./cmd/netsynth/ --help 2>&1 | grep -q "\-o.*output" && echo "OK"</automated>
|
|
</verify>
|
|
<acceptance_criteria>
|
|
- cmd/netsynth/main.go contains `var outputPath string`
|
|
- cmd/netsynth/main.go contains `StringVarP(&outputPath, "output", "o",`
|
|
- cmd/netsynth/main.go contains `netsynth-%s.mp3`
|
|
- cmd/netsynth/main.go contains `time.Now().Format("20060102-150405")`
|
|
- cmd/netsynth/main.go imports `"time"`
|
|
- cmd/netsynth/main.go contains `var collectedSnapshots []classify.WindowSnapshot`
|
|
- cmd/netsynth/main.go contains `TODO(phase-3)` referencing `encode.RunSynthesis`
|
|
- `go build ./cmd/netsynth/` exits 0
|
|
- `go run ./cmd/netsynth/ --help` output contains `-o, --output`
|
|
</acceptance_criteria>
|
|
<done>The -o/--output flag is registered in Cobra, defaults to netsynth-<timestamp>.mp3, visible in --help. Snapshot slice accumulator stub is in place for Phase 3 wiring. Build succeeds.</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- `CGO_ENABLED=1 go test ./...` passes all tests (synth + encode + existing)
|
|
- `ffprobe` validates the test-generated MP3 (within encode test)
|
|
- `go run ./cmd/netsynth/ --help` shows `-o, --output` flag
|
|
- `grep "no packets captured" encode/mp3.go` confirms zero-packet error message
|
|
- `grep "collectedSnapshots" cmd/netsynth/main.go` confirms snapshot accumulator stub
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- encode/mp3.go produces valid MP3 files from synthetic WindowSnapshots (validated by ffprobe)
|
|
- Zero-packet guard prevents file creation and returns descriptive error (OUT-03)
|
|
- -o flag registered in CLI with timestamp default (OUT-01)
|
|
- Snapshot slice accumulator ready for Phase 3 wiring
|
|
- Full test suite passes: `CGO_ENABLED=1 go test ./...`
|
|
- Complete Phase 2 audio pipeline validated end-to-end against synthetic data
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/02-audio-synthesis-engine/02-03-SUMMARY.md`
|
|
</output>
|