101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
|
---
|
||
|
|
phase: 02-audio-synthesis-engine
|
||
|
|
plan: 03
|
||
|
|
subsystem: encode
|
||
|
|
tags: [mp3, encoding, go-lame, cli, output-flag, tdd]
|
||
|
|
dependency_graph:
|
||
|
|
requires: [02-01, 02-02]
|
||
|
|
provides: [encode/mp3.go, encode/mp3_test.go, cmd/netsynth/-o-flag]
|
||
|
|
affects: [cmd/netsynth/main.go]
|
||
|
|
tech_stack:
|
||
|
|
added: [github.com/sjzar/go-lame (used directly)]
|
||
|
|
patterns: [go-lame LameWriter API, zero-packet guard before file creation, TDD red-green workflow]
|
||
|
|
key_files:
|
||
|
|
created:
|
||
|
|
- encode/mp3.go
|
||
|
|
- encode/mp3_test.go
|
||
|
|
modified:
|
||
|
|
- cmd/netsynth/main.go
|
||
|
|
decisions:
|
||
|
|
- "EncodeMP3 and RunSynthesis separated into distinct functions to enable independent testing of raw-frame encoding vs full pipeline"
|
||
|
|
- "RunSynthesis takes []classify.WindowSnapshot slice (not channel) — caller collects from channel enabling zero-packet check before file creation"
|
||
|
|
- "Zero-packet guard checks totalPackets BEFORE os.Create to ensure no empty file is left on disk"
|
||
|
|
- "Snapshot accumulator uses _ = collectedSnapshots to suppress unused variable error without importing encode package prematurely"
|
||
|
|
metrics:
|
||
|
|
duration: 3min
|
||
|
|
completed: 2026-03-26
|
||
|
|
tasks_completed: 2
|
||
|
|
files_created: 2
|
||
|
|
files_modified: 1
|
||
|
|
---
|
||
|
|
|
||
|
|
# Phase 2 Plan 3: MP3 Encoder and Output Flag Summary
|
||
|
|
|
||
|
|
**One-liner:** MP3 encoder via go-lame (44100 Hz, 128 kbps) with ffprobe-validated tests, zero-packet guard, and -o CLI flag with timestamp default.
|
||
|
|
|
||
|
|
## What Was Built
|
||
|
|
|
||
|
|
### Task 1: MP3 encoder package (TDD)
|
||
|
|
|
||
|
|
**encode/mp3.go** implements two functions:
|
||
|
|
|
||
|
|
- `EncodeMP3(outputPath string, frames [][2]float64, sampleRate int) error` — Creates an MP3 file from stereo PCM frames using go-lame's LameWriter. Sets 44100 Hz input/output sample rate, 128 kbps bitrate, stereo (2 channels), quality 5. Calls `InitParams()` after all `Set*` calls (required by go-lame API). Writes all PCM bytes in a single call.
|
||
|
|
|
||
|
|
- `RunSynthesis(snapshots []classify.WindowSnapshot, outputPath string) error` — Orchestrates the full pipeline: checks total packet count (zero-packet guard before file creation), creates `OscillatorBank` with tau=1.0, renders each snapshot via `bank.RenderWindow`, concatenates all frames, and calls `EncodeMP3`.
|
||
|
|
|
||
|
|
**encode/mp3_test.go** implements three tests, all ffprobe-validated:
|
||
|
|
- `TestMP3Valid` — 3 synthetic snapshots (ICMP=50+DNS=30, HTTPS=200, SSH=10+HTTP=80) through full pipeline; ffprobe confirms MP3 format, duration > 0
|
||
|
|
- `TestZeroPacketError` — empty slice and zero-count snapshots return error containing "no packets"; output file does not exist on disk
|
||
|
|
- `TestEncodeMP3DirectBytes` — 44100 frames of 440 Hz sine wave encoded directly; ffprobe confirms MP3 output
|
||
|
|
|
||
|
|
### Task 2: -o output flag and snapshot accumulator stub
|
||
|
|
|
||
|
|
**cmd/netsynth/main.go** additions:
|
||
|
|
- `var outputPath string` package-level var
|
||
|
|
- `-o`/`--output` Cobra flag with descriptive help text
|
||
|
|
- Timestamp default resolution: `netsynth-<20060102-150405>.mp3` format when flag omitted
|
||
|
|
- Snapshot accumulator loop collects `[]classify.WindowSnapshot` alongside existing totals accumulation
|
||
|
|
- `TODO(phase-3)` comment marking the synthesis integration point
|
||
|
|
|
||
|
|
## Test Results
|
||
|
|
|
||
|
|
```
|
||
|
|
ok github.com/netsynth/netsynth/aggregate 0.145s
|
||
|
|
ok github.com/netsynth/netsynth/capture 0.009s
|
||
|
|
ok github.com/netsynth/netsynth/classify 0.007s
|
||
|
|
ok github.com/netsynth/netsynth/cmd/netsynth 0.021s
|
||
|
|
ok github.com/netsynth/netsynth/encode 0.283s
|
||
|
|
ok github.com/netsynth/netsynth/synth 0.680s
|
||
|
|
```
|
||
|
|
|
||
|
|
## Deviations from Plan
|
||
|
|
|
||
|
|
None — plan executed exactly as written.
|
||
|
|
|
||
|
|
## Commits
|
||
|
|
|
||
|
|
| Hash | Type | Description |
|
||
|
|
|------|------|-------------|
|
||
|
|
| ed3a562 | test | Add failing tests for MP3 encoder and RunSynthesis (RED) |
|
||
|
|
| f221963 | feat | Implement MP3 encoder package with RunSynthesis orchestrator (GREEN) |
|
||
|
|
| a65dfcd | feat | Wire -o output flag and snapshot accumulator stub into CLI |
|
||
|
|
|
||
|
|
## Phase 2 Completion
|
||
|
|
|
||
|
|
This plan completes Phase 2 (audio-synthesis-engine). The full synthesis chain is now validated end-to-end:
|
||
|
|
|
||
|
|
```
|
||
|
|
WindowSnapshot -> OscillatorBank.RenderWindow -> [][2]float64 -> StereoFramesToInt16Bytes -> go-lame LameWriter -> MP3 file
|
||
|
|
```
|
||
|
|
|
||
|
|
Phase 3 will wire `encode.RunSynthesis(collectedSnapshots, outputPath)` into the live capture pipeline.
|
||
|
|
|
||
|
|
## Self-Check
|
||
|
|
|
||
|
|
Files created/modified:
|
||
|
|
- encode/mp3.go: EXISTS
|
||
|
|
- encode/mp3_test.go: EXISTS
|
||
|
|
- cmd/netsynth/main.go: MODIFIED
|
||
|
|
|
||
|
|
Commits verified: ed3a562, f221963, a65dfcd
|