ci/tasks/readme: register sfx-maker (sfxc)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MmdG9GqfSWCzts7AkDwRDh

.gitea/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - name: Detektera ändrade tools
         id: changed
         run: |
-          TOOLS="pixel-sprite-maker mesh-tool bitmap-font-maker"
+          TOOLS="pixel-sprite-maker mesh-tool bitmap-font-maker sfx-maker"
           BEFORE="${{ github.event.before }}"
           CHANGED=""
           if [ "${{ github.event_name }}" = "workflow_dispatch" ] \
@@ -57,6 +57,7 @@ jobs:
               pixel-sprite-maker) BIN=spritec ;;
               mesh-tool)          BIN=mesht ;;
               bitmap-font-maker)  BIN=fontc ;;
+              sfx-maker)          BIN=sfxc ;;
               *) echo "okänt tool $t"; exit 1 ;;
             esac
             echo "=== $t ($BIN) ==="
@@ -84,6 +85,7 @@ jobs:
               pixel-sprite-maker) BIN=spritec ;;
               mesh-tool)          BIN=mesht ;;
               bitmap-font-maker)  BIN=fontc ;;
+              sfx-maker)          BIN=sfxc ;;
             esac
             TAG="$t-latest"
             BODY="$t (binär: $BIN) - rullande bygge från senaste master. Commit: ${{ github.sha }}. Arkitekturer: linux x64 + arm64 (Pi5)."

.vscode/tasks.json

@@ -33,6 +33,22 @@
       "group": "test",
       "problemMatcher": ["$go"]
     },
+    {
+      "label": "build sfx-maker",
+      "type": "shell",
+      "command": "go build -trimpath -ldflags '-s -w' -o build/sfxc .",
+      "options": { "cwd": "${workspaceFolder}/sfx-maker" },
+      "group": "build",
+      "problemMatcher": ["$go"]
+    },
+    {
+      "label": "test sfx-maker",
+      "type": "shell",
+      "command": "go test ./...",
+      "options": { "cwd": "${workspaceFolder}/sfx-maker" },
+      "group": "test",
+      "problemMatcher": ["$go"]
+    },
     {
       "label": "test pixel-sprite-maker",
       "type": "shell",
@@ -51,7 +67,7 @@
     },
     {
       "label": "build",
-      "dependsOn": ["build pixel-sprite-maker", "build mesh-tool", "build bitmap-font-maker"],
+      "dependsOn": ["build pixel-sprite-maker", "build mesh-tool", "build bitmap-font-maker", "build sfx-maker"],
       "dependsOrder": "parallel",
       "group": { "kind": "build", "isDefault": true },
       "problemMatcher": []

README.md

@@ -11,6 +11,7 @@ agent understands the result without opening an image viewer.
 | [`pixel-sprite-maker/`](pixel-sprite-maker/) | `spritec` | Turns `.sprite` text files (palette + character grid) into PNG/JPG/SVG pixel art, up to 256x256 px per sprite. Combines several sprites into sprite sheets / animation strips whose **file names document the layout** (`walk_8x8_4x1.png` = 8x8 px frames, 4 columns, 1 row). |
 | [`mesh-tool/`](mesh-tool/) | `mesht` | Creates, inspects and edits 3D models (OBJ + STL). ASCII multi-view rendering + measurements (bbox, volume, watertightness) let an agent *see* a model, edit it (scale/rotate/mirror/merge/primitives) and verify the result. |
 | [`bitmap-font-maker/`](bitmap-font-maker/) | `fontc` | Turns `.font` text files (pixel glyph grids, proportional widths) into font atlases (PNG + JSON metrics) and renders text strings to PNG or the terminal. |
+| [`sfx-maker/`](sfx-maker/) | `sfxc` | Synthesizes retro game sound effects (sfxr-style) from `.sfx` text presets to 16-bit WAV: waves, envelope, pitch slides, vibrato, arpeggio, filters. Deterministic, with built-in presets (jump, coin, laser…). |
 
 Each tool has its own folder, its own README with the full format/CLI
 reference, its own tests and its own dev branch (`dev/<tool>`).

sfx-maker/README.md

@@ -0,0 +1,68 @@
+# sfx-maker (`sfxc`)
+
+Synthesizes **retro game sound effects** (sfxr-style) from `.sfx` text
+files and writes 16-bit mono **WAV**. Sound design becomes text an agent
+can read, tweak and reason about — no DAW needed. Go, zero
+dependencies, single static binary.
+
+## Build
+
+```bash
+# Arch/Garuda: sudo pacman -S go
+cd sfx-maker
+go build -o build/sfxc .        # or the VS Code task "build sfx-maker"
+go test ./...
+```
+
+## Quick start
+
+```bash
+sfxc preset jump -o jump.sfx      # editable text preset
+sfxc build jump.sfx               # -> jump.wav
+mpv jump.wav                      # listen (or aplay/ffplay)
+
+sfxc preset coin -o coin.wav      # straight to WAV
+sfxc preset coin --seed 3 -o coin3.wav    # deterministic variant
+sfxc info laser.sfx               # validate + summary
+```
+
+Presets: `blip, coin, explosion, hurt, jump, laser, powerup`.
+`--seed 0` is the canonical sound; any other seed nudges pitch/length
+deterministically — ask for three seeds, keep the one that sounds best.
+
+## The `.sfx` format
+
+```
+# comment
+sfx: jump            name
+wave: square         square | saw | sine | triangle | noise
+volume: 0.7          0..1
+attack: 0.01         seconds: fade in
+sustain: 0.08        hold at full volume
+decay: 0.18          fade out (total length = a+s+d, max 10 s)
+freq: 330            start pitch, Hz
+freq-slide: 900      Hz/second (positive = rising, negative = falling)
+duty: 0.5            square pulse width 0.05..0.95 (thinner = buzzier)
+vibrato-depth: 25    pitch wobble, Hz
+vibrato-rate: 9      wobbles per second
+arpeggio: 1.335      multiply pitch by this...
+arpeggio-time: 0.06  ...after this many seconds (classic coin blip)
+lowpass: 2200        cutoff Hz (muffle: explosions, thuds)
+highpass: 300        cutoff Hz (thin out: lasers, clicks)
+sample-rate: 44100   8000-96000
+seed: 1              noise randomness — same seed = same sound
+```
+
+Unknown keys are **errors**, so typos surface immediately. Everything is
+deterministic: same file → byte-identical WAV.
+
+## Recipe intuition for agents
+
+- **Jump**: square wave + rising `freq-slide`.
+- **Coin/pickup**: square + `arpeggio` > 1 shortly after the start.
+- **Laser**: saw + steep negative `freq-slide` + `highpass`.
+- **Explosion**: noise + `lowpass` ~2 kHz + long `decay`.
+- **Hurt**: saw, low pitch, quick fall.
+- **Power-up**: rising slide + `vibrato`.
+
+[`examples/`](examples/) contains all presets as `.sfx` + rendered `.wav`.

sfx-maker/examples/blip.sfx

@@ -0,0 +1,9 @@
+# blip preset (seed 0) — edit freely, then: sfxc build examples/blip.sfx
+sfx: blip
+wave: square
+volume: 0.7
+attack: 0.002
+sustain: 0.03
+decay: 0.05
+freq: 660
+duty: 0.4

sfx-maker/examples/coin.sfx

@@ -0,0 +1,10 @@
+# coin preset (seed 0) — edit freely, then: sfxc build examples/coin.sfx
+sfx: coin
+wave: square
+volume: 0.7
+attack: 0.005
+sustain: 0.08
+decay: 0.25
+freq: 988
+arpeggio: 1.335
+arpeggio-time: 0.06

sfx-maker/examples/explosion.sfx

@@ -0,0 +1,9 @@
+# explosion preset (seed 0) — edit freely, then: sfxc build examples/explosion.sfx
+sfx: explosion
+wave: noise
+volume: 0.7
+attack: 0.01
+sustain: 0.15
+decay: 0.55
+freq-slide: -600
+lowpass: 2200

sfx-maker/examples/hurt.sfx

@@ -0,0 +1,9 @@
+# hurt preset (seed 0) — edit freely, then: sfxc build examples/hurt.sfx
+sfx: hurt
+wave: saw
+volume: 0.7
+attack: 0.005
+sustain: 0.04
+decay: 0.14
+freq: 300
+freq-slide: -700

sfx-maker/examples/jump.sfx

@@ -0,0 +1,9 @@
+# jump preset (seed 0) — edit freely, then: sfxc build examples/jump.sfx
+sfx: jump
+wave: square
+volume: 0.7
+attack: 0.01
+sustain: 0.08
+decay: 0.18
+freq: 330
+freq-slide: 900

sfx-maker/examples/laser.sfx

@@ -0,0 +1,10 @@
+# laser preset (seed 0) — edit freely, then: sfxc build examples/laser.sfx
+sfx: laser
+wave: saw
+volume: 0.7
+attack: 0.005
+sustain: 0.05
+decay: 0.12
+freq: 1400
+freq-slide: -6000
+highpass: 300

sfx-maker/examples/powerup.sfx

@@ -0,0 +1,12 @@
+# powerup preset (seed 0) — edit freely, then: sfxc build examples/powerup.sfx
+sfx: powerup
+wave: square
+volume: 0.7
+attack: 0.01
+sustain: 0.25
+decay: 0.25
+freq: 220
+freq-slide: 700
+duty: 0.4
+vibrato-depth: 25
+vibrato-rate: 9

sfx-maker/go.mod

@@ -0,0 +1,3 @@
+module gitea.brasse-pc.eu/brasse/agent-tools/sfx-maker
+
+go 1.24

sfx-maker/main.go

@@ -0,0 +1,212 @@
+// sfxc synthesizes retro game sound effects from .sfx text files
+// (sfxr-style parameters) and writes 16-bit mono WAV.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"gitea.brasse-pc.eu/brasse/agent-tools/sfx-maker/sfx"
+)
+
+var version = "dev"
+
+const usage = `sfxc - sound effect maker for agents
+
+Usage:
+  sfxc build <file.sfx> [-o out.wav]      synthesize a .sfx file to WAV
+  sfxc preset <name> [-o out.sfx|out.wav] [--seed n]
+                                          write a preset (editable .sfx text,
+                                          or straight to .wav)
+  sfxc info <file.sfx>                    validate + print parameters
+  sfxc version
+
+Presets: blip, coin, explosion, hurt, jump, laser, powerup
+--seed 0 (default) is the canonical sound; other seeds give variants.
+
+The .sfx format (all keys optional, '#' comments):
+  sfx: jump            name
+  wave: square         square | saw | sine | triangle | noise
+  volume: 0.7          0..1
+  attack: 0.01         seconds: fade in
+  sustain: 0.08        hold
+  decay: 0.18          fade out
+  freq: 330            start pitch, Hz
+  freq-slide: 900      Hz per second (negative = falling)
+  duty: 0.5            square pulse width 0.05..0.95
+  vibrato-depth: 25    Hz
+  vibrato-rate: 9      Hz
+  arpeggio: 1.335      pitch multiplier that kicks in at...
+  arpeggio-time: 0.06  ...this many seconds
+  lowpass: 2200        filter cutoff Hz
+  highpass: 300        filter cutoff Hz
+  sample-rate: 44100
+  seed: 1              noise randomness (deterministic)
+
+Play the result with e.g.:  mpv out.wav   or   aplay out.wav
+`
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Print(usage)
+		os.Exit(2)
+	}
+	switch os.Args[1] {
+	case "build":
+		cmdBuild(os.Args[2:])
+	case "preset":
+		cmdPreset(os.Args[2:])
+	case "info":
+		cmdInfo(os.Args[2:])
+	case "version", "--version", "-v":
+		fmt.Println("sfxc", version)
+	case "help", "--help", "-h":
+		fmt.Print(usage)
+	default:
+		die("unknown command %q — run 'sfxc help'", os.Args[1])
+	}
+}
+
+// parseInterspersed lets flags appear before or after positional args.
+func parseInterspersed(fs *flag.FlagSet, args []string) {
+	var flags, pos []string
+	for i := 0; i < len(args); i++ {
+		a := args[i]
+		if len(a) > 1 && a[0] == '-' {
+			flags = append(flags, a)
+			name := strings.TrimLeft(a, "-")
+			if !strings.Contains(name, "=") {
+				f := fs.Lookup(name)
+				isBool := false
+				if f != nil {
+					if bv, ok := f.Value.(interface{ IsBoolFlag() bool }); ok && bv.IsBoolFlag() {
+						isBool = true
+					}
+				}
+				if !isBool && i+1 < len(args) {
+					i++
+					flags = append(flags, args[i])
+				}
+			}
+		} else {
+			pos = append(pos, a)
+		}
+	}
+	fs.Parse(append(flags, pos...))
+}
+
+func writeWAVFile(path string, p *sfx.Params) error {
+	samples := sfx.Render(p)
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	if err := sfx.WriteWAV(f, samples, p.SampleRate); err != nil {
+		return err
+	}
+	return f.Close()
+}
+
+func cmdBuild(args []string) {
+	fs := flag.NewFlagSet("build", flag.ExitOnError)
+	out := fs.String("o", "", "output .wav (default: input name with .wav)")
+	parseInterspersed(fs, args)
+	if fs.NArg() != 1 {
+		die("build takes exactly one .sfx file")
+	}
+	p, err := sfx.ParseFile(fs.Arg(0))
+	if err != nil {
+		die("%v", err)
+	}
+	path := *out
+	if path == "" {
+		path = strings.TrimSuffix(fs.Arg(0), filepath.Ext(fs.Arg(0))) + ".wav"
+	}
+	if err := writeWAVFile(path, p); err != nil {
+		die("%v", err)
+	}
+	fmt.Printf("%s  (%s, %.2fs, %d Hz)\n", path, p.Wave, p.Duration(), p.SampleRate)
+}
+
+func cmdPreset(args []string) {
+	fs := flag.NewFlagSet("preset", flag.ExitOnError)
+	out := fs.String("o", "", "output file: .sfx (editable text) or .wav (rendered)")
+	seed := fs.Int64("seed", 0, "0 = canonical, other values = variants")
+	parseInterspersed(fs, args)
+	if fs.NArg() != 1 {
+		die("preset takes exactly one preset name (%s)", sfx.PresetNames())
+	}
+	name := fs.Arg(0)
+	p, err := sfx.Preset(name, *seed)
+	if err != nil {
+		die("%v", err)
+	}
+	path := *out
+	if path == "" {
+		path = name + ".sfx"
+	}
+	switch strings.ToLower(filepath.Ext(path)) {
+	case ".wav":
+		if err := writeWAVFile(path, p); err != nil {
+			die("%v", err)
+		}
+		fmt.Printf("%s  (%s preset, seed %d, %.2fs)\n", path, name, *seed, p.Duration())
+	case ".sfx":
+		f, err := os.Create(path)
+		if err != nil {
+			die("%v", err)
+		}
+		defer f.Close()
+		comment := fmt.Sprintf("%s preset (seed %d) — edit freely, then: sfxc build %s", name, *seed, path)
+		if err := p.Write(f, comment); err != nil {
+			die("%v", err)
+		}
+		fmt.Printf("%s  (%s preset, seed %d — edit then 'sfxc build')\n", path, name, *seed)
+	default:
+		die("-o must end in .sfx or .wav")
+	}
+}
+
+func cmdInfo(args []string) {
+	if len(args) != 1 {
+		die("info takes exactly one .sfx file")
+	}
+	p, err := sfx.ParseFile(args[0])
+	if err != nil {
+		die("%v", err)
+	}
+	fmt.Printf("sfx:       %s\n", p.Name)
+	fmt.Printf("wave:      %s\n", p.Wave)
+	fmt.Printf("duration:  %.3fs (attack %.3g + sustain %.3g + decay %.3g)\n",
+		p.Duration(), p.Attack, p.Sustain, p.Decay)
+	if p.Wave != "noise" {
+		fmt.Printf("freq:      %g Hz", p.Freq)
+		if p.FreqSlide != 0 {
+			fmt.Printf("  (slide %+g Hz/s)", p.FreqSlide)
+		}
+		fmt.Println()
+	}
+	if p.ArpFactor != 0 {
+		fmt.Printf("arpeggio:  x%g at %gs\n", p.ArpFactor, p.ArpTime)
+	}
+	if p.VibratoDepth > 0 {
+		fmt.Printf("vibrato:   ±%g Hz at %g Hz\n", p.VibratoDepth, p.VibratoRate)
+	}
+	if p.LowPass > 0 {
+		fmt.Printf("lowpass:   %g Hz\n", p.LowPass)
+	}
+	if p.HighPass > 0 {
+		fmt.Printf("highpass:  %g Hz\n", p.HighPass)
+	}
+	fmt.Printf("volume:    %g\nsamplerate:%d\n", p.Volume, p.SampleRate)
+	fmt.Println("valid:     yes")
+}
+
+func die(format string, a ...any) {
+	fmt.Fprintf(os.Stderr, "sfxc: "+format+"\n", a...)
+	os.Exit(1)
+}

sfx-maker/sfx/params.go

@@ -0,0 +1,223 @@
+// Package sfx synthesizes retro game sound effects (sfxr-style) from
+// text parameter files and renders them to 16-bit mono WAV.
+package sfx
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// Params describes one sound effect. Zero values mean "off" for the
+// optional effects; Defaults() fills the required fields.
+type Params struct {
+	Name string
+	Wave string // square | saw | sine | triangle | noise
+
+	Volume float64 // 0..1 master gain
+
+	// envelope, seconds
+	Attack  float64 // 0 -> Volume
+	Sustain float64 // hold at Volume
+	Decay   float64 // Volume -> 0
+
+	Freq      float64 // start frequency, Hz
+	FreqSlide float64 // Hz per second, may be negative
+	FreqMin   float64 // clamp; sound stops below this (default 20 Hz)
+
+	Duty float64 // square wave duty cycle 0.05..0.95 (default 0.5)
+
+	VibratoDepth float64 // Hz
+	VibratoRate  float64 // Hz
+
+	ArpFactor float64 // frequency multiplier applied at ArpTime (0 = off)
+	ArpTime   float64 // seconds
+
+	LowPass  float64 // cutoff Hz (0 = off)
+	HighPass float64 // cutoff Hz (0 = off)
+
+	SampleRate int   // default 44100
+	Seed       int64 // noise seed (default 1)
+}
+
+// Defaults returns a Params with sensible base values.
+func Defaults() Params {
+	return Params{
+		Wave:       "square",
+		Volume:     0.7,
+		Attack:     0.01,
+		Sustain:    0.1,
+		Decay:      0.15,
+		Freq:       440,
+		FreqMin:    20,
+		Duty:       0.5,
+		SampleRate: 44100,
+		Seed:       1,
+	}
+}
+
+// Duration is the total length of the sound in seconds.
+func (p *Params) Duration() float64 { return p.Attack + p.Sustain + p.Decay }
+
+// Validate checks ranges and returns a helpful error.
+func (p *Params) Validate() error {
+	switch p.Wave {
+	case "square", "saw", "sine", "triangle", "noise":
+	default:
+		return fmt.Errorf("wave %q must be square, saw, sine, triangle or noise", p.Wave)
+	}
+	if p.Volume < 0 || p.Volume > 1 {
+		return fmt.Errorf("volume %g out of range 0-1", p.Volume)
+	}
+	if p.Attack < 0 || p.Sustain < 0 || p.Decay < 0 {
+		return fmt.Errorf("attack/sustain/decay must be >= 0")
+	}
+	if p.Duration() <= 0 {
+		return fmt.Errorf("total duration is 0 — set attack, sustain and/or decay")
+	}
+	if p.Duration() > 10 {
+		return fmt.Errorf("total duration %.2fs is too long (max 10s)", p.Duration())
+	}
+	if p.Wave != "noise" && (p.Freq <= 0 || p.Freq > 20000) {
+		return fmt.Errorf("freq %g out of range 1-20000 Hz", p.Freq)
+	}
+	if p.Duty < 0.05 || p.Duty > 0.95 {
+		return fmt.Errorf("duty %g out of range 0.05-0.95", p.Duty)
+	}
+	if p.SampleRate < 8000 || p.SampleRate > 96000 {
+		return fmt.Errorf("sample-rate %d out of range 8000-96000", p.SampleRate)
+	}
+	return nil
+}
+
+// ParseFile reads a .sfx file; the name defaults to the file name.
+func ParseFile(path string) (*Params, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	p, err := Parse(f)
+	if err != nil {
+		return nil, fmt.Errorf("%s: %w", path, err)
+	}
+	if p.Name == "" {
+		p.Name = strings.TrimSuffix(filepath.Base(path), filepath.Ext(path))
+	}
+	return p, nil
+}
+
+// Parse reads the .sfx text format: one "key: value" per line,
+// '#' comments. Unknown keys are errors so typos surface immediately.
+func Parse(r io.Reader) (*Params, error) {
+	p := Defaults()
+	sc := bufio.NewScanner(r)
+	lineNo := 0
+	for sc.Scan() {
+		lineNo++
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		i := strings.Index(line, ":")
+		if i < 0 {
+			return nil, fmt.Errorf("line %d: want 'key: value', got %q", lineNo, line)
+		}
+		key := strings.ToLower(strings.TrimSpace(line[:i]))
+		val := strings.TrimSpace(line[i+1:])
+		if j := strings.Index(val, " #"); j >= 0 { // trailing comment
+			val = strings.TrimSpace(val[:j])
+		}
+		var err error
+		switch key {
+		case "sfx", "name":
+			p.Name = val
+		case "wave":
+			p.Wave = strings.ToLower(val)
+		case "volume":
+			p.Volume, err = strconv.ParseFloat(val, 64)
+		case "attack":
+			p.Attack, err = strconv.ParseFloat(val, 64)
+		case "sustain":
+			p.Sustain, err = strconv.ParseFloat(val, 64)
+		case "decay":
+			p.Decay, err = strconv.ParseFloat(val, 64)
+		case "freq":
+			p.Freq, err = strconv.ParseFloat(val, 64)
+		case "freq-slide":
+			p.FreqSlide, err = strconv.ParseFloat(val, 64)
+		case "freq-min":
+			p.FreqMin, err = strconv.ParseFloat(val, 64)
+		case "duty":
+			p.Duty, err = strconv.ParseFloat(val, 64)
+		case "vibrato-depth":
+			p.VibratoDepth, err = strconv.ParseFloat(val, 64)
+		case "vibrato-rate":
+			p.VibratoRate, err = strconv.ParseFloat(val, 64)
+		case "arpeggio":
+			p.ArpFactor, err = strconv.ParseFloat(val, 64)
+		case "arpeggio-time":
+			p.ArpTime, err = strconv.ParseFloat(val, 64)
+		case "lowpass":
+			p.LowPass, err = strconv.ParseFloat(val, 64)
+		case "highpass":
+			p.HighPass, err = strconv.ParseFloat(val, 64)
+		case "sample-rate":
+			p.SampleRate, err = strconv.Atoi(val)
+		case "seed":
+			p.Seed, err = strconv.ParseInt(val, 10, 64)
+		default:
+			return nil, fmt.Errorf("line %d: unknown key %q", lineNo, key)
+		}
+		if err != nil {
+			return nil, fmt.Errorf("line %d: %s: bad value %q", lineNo, key, val)
+		}
+	}
+	if err := sc.Err(); err != nil {
+		return nil, err
+	}
+	if err := p.Validate(); err != nil {
+		return nil, err
+	}
+	return &p, nil
+}
+
+// Write renders the params back to the .sfx text format (used by the
+// preset generator so agents get an editable file).
+func (p *Params) Write(w io.Writer, comment string) error {
+	bw := bufio.NewWriter(w)
+	if comment != "" {
+		fmt.Fprintf(bw, "# %s\n", comment)
+	}
+	fmt.Fprintf(bw, "sfx: %s\nwave: %s\nvolume: %g\n", p.Name, p.Wave, p.Volume)
+	fmt.Fprintf(bw, "attack: %g\nsustain: %g\ndecay: %g\n", p.Attack, p.Sustain, p.Decay)
+	if p.Wave != "noise" {
+		fmt.Fprintf(bw, "freq: %g\n", p.Freq)
+	}
+	if p.FreqSlide != 0 {
+		fmt.Fprintf(bw, "freq-slide: %g\n", p.FreqSlide)
+	}
+	if p.Wave == "square" && p.Duty != 0.5 {
+		fmt.Fprintf(bw, "duty: %g\n", p.Duty)
+	}
+	if p.VibratoDepth > 0 && p.VibratoRate > 0 {
+		fmt.Fprintf(bw, "vibrato-depth: %g\nvibrato-rate: %g\n", p.VibratoDepth, p.VibratoRate)
+	}
+	if p.ArpFactor != 0 {
+		fmt.Fprintf(bw, "arpeggio: %g\narpeggio-time: %g\n", p.ArpFactor, p.ArpTime)
+	}
+	if p.LowPass > 0 {
+		fmt.Fprintf(bw, "lowpass: %g\n", p.LowPass)
+	}
+	if p.HighPass > 0 {
+		fmt.Fprintf(bw, "highpass: %g\n", p.HighPass)
+	}
+	if p.Seed != 1 {
+		fmt.Fprintf(bw, "seed: %d\n", p.Seed)
+	}
+	return bw.Flush()
+}

sfx-maker/sfx/presets.go

@@ -0,0 +1,114 @@
+package sfx
+
+import (
+	"fmt"
+	"math/rand"
+	"sort"
+)
+
+// Preset returns ready-made parameters for classic game sounds.
+// seed 0 gives the canonical version; other seeds vary it slightly so
+// agents can generate alternatives ("give me three coin variants").
+func Preset(name string, seed int64) (*Params, error) {
+	p := Defaults()
+	p.Name = name
+	switch name {
+	case "jump":
+		p.Wave = "square"
+		p.Duty = 0.5
+		p.Freq = 330
+		p.FreqSlide = 900
+		p.Attack = 0.01
+		p.Sustain = 0.08
+		p.Decay = 0.18
+	case "coin":
+		p.Wave = "square"
+		p.Duty = 0.5
+		p.Freq = 988
+		p.ArpFactor = 1.335 // up a fourth: B5 -> E6
+		p.ArpTime = 0.06
+		p.Attack = 0.005
+		p.Sustain = 0.08
+		p.Decay = 0.25
+	case "laser":
+		p.Wave = "saw"
+		p.Freq = 1400
+		p.FreqSlide = -6000
+		p.Attack = 0.005
+		p.Sustain = 0.05
+		p.Decay = 0.12
+		p.HighPass = 300
+	case "explosion":
+		p.Wave = "noise"
+		p.Freq = 900
+		p.FreqSlide = -600
+		p.Attack = 0.01
+		p.Sustain = 0.15
+		p.Decay = 0.55
+		p.LowPass = 2200
+	case "hurt":
+		p.Wave = "saw"
+		p.Freq = 300
+		p.FreqSlide = -700
+		p.Attack = 0.005
+		p.Sustain = 0.04
+		p.Decay = 0.14
+	case "powerup":
+		p.Wave = "square"
+		p.Duty = 0.4
+		p.Freq = 220
+		p.FreqSlide = 700
+		p.VibratoDepth = 25
+		p.VibratoRate = 9
+		p.Attack = 0.01
+		p.Sustain = 0.25
+		p.Decay = 0.25
+	case "blip":
+		p.Wave = "square"
+		p.Duty = 0.4
+		p.Freq = 660
+		p.Attack = 0.002
+		p.Sustain = 0.03
+		p.Decay = 0.05
+	default:
+		return nil, fmt.Errorf("unknown preset %q (available: %s)", name, PresetNames())
+	}
+	if seed != 0 {
+		vary(&p, seed)
+	}
+	if err := p.Validate(); err != nil {
+		return nil, fmt.Errorf("preset %s (seed %d): %w", name, seed, err)
+	}
+	return &p, nil
+}
+
+// vary nudges the tonal parameters deterministically from the seed.
+func vary(p *Params, seed int64) {
+	rng := rand.New(rand.NewSource(seed))
+	jitter := func(v, amount float64) float64 {
+		return v * (1 + amount*(rng.Float64()*2-1))
+	}
+	p.Freq = jitter(p.Freq, 0.15)
+	p.FreqSlide = jitter(p.FreqSlide, 0.25)
+	p.Sustain = jitter(p.Sustain, 0.2)
+	p.Decay = jitter(p.Decay, 0.2)
+	if p.ArpFactor != 0 {
+		p.ArpFactor = jitter(p.ArpFactor, 0.05)
+	}
+	p.Seed = seed // noise variation too
+}
+
+var presetNames = []string{"blip", "coin", "explosion", "hurt", "jump", "laser", "powerup"}
+
+// PresetNames lists the available presets, sorted.
+func PresetNames() string {
+	sort.Strings(presetNames)
+	out := ""
+	for i, n := range presetNames {
+		if i > 0 {
+			out += ", "
+		}
+		out += n
+	}
+	return out
+}

sfx-maker/sfx/sfx_test.go

@@ -0,0 +1,164 @@
+package sfx
+
+import (
+	"bytes"
+	"math"
+	"strings"
+	"testing"
+)
+
+func TestParseAndValidate(t *testing.T) {
+	src := `
+# a jump
+sfx: jump
+wave: square
+freq: 330
+freq-slide: 900
+attack: 0.01
+sustain: 0.08
+decay: 0.18
+duty: 0.4
+`
+	p, err := Parse(strings.NewReader(src))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if p.Name != "jump" || p.Wave != "square" || p.Freq != 330 || p.Duty != 0.4 {
+		t.Errorf("parsed wrong: %+v", p)
+	}
+	if math.Abs(p.Duration()-0.27) > 1e-9 {
+		t.Errorf("duration = %g, want 0.27", p.Duration())
+	}
+}
+
+func TestParseErrors(t *testing.T) {
+	cases := map[string]string{
+		"unknown key":  "wat: 3\n",
+		"bad wave":     "wave: wobble\n",
+		"bad value":    "freq: abc\n",
+		"zero length":  "attack: 0\nsustain: 0\ndecay: 0\n",
+		"volume range": "volume: 2\n",
+		"duty range":   "duty: 0.99\n",
+	}
+	for name, src := range cases {
+		if _, err := Parse(strings.NewReader(src)); err == nil {
+			t.Errorf("%s: expected error", name)
+		}
+	}
+}
+
+func TestRenderBasics(t *testing.T) {
+	p := Defaults()
+	p.Wave = "sine"
+	p.Attack, p.Sustain, p.Decay = 0.01, 0.05, 0.05
+	samples := Render(&p)
+	want := int(0.11 * 44100)
+	if len(samples) != want {
+		t.Errorf("samples = %d, want %d", len(samples), want)
+	}
+	var peak float64
+	for _, s := range samples {
+		if math.Abs(s) > peak {
+			peak = math.Abs(s)
+		}
+		if s > 1 || s < -1 {
+			t.Fatalf("sample %g out of range", s)
+		}
+	}
+	if peak < 0.5 {
+		t.Errorf("peak %g suspiciously quiet", peak)
+	}
+	// end of decay should be silent-ish
+	tail := samples[len(samples)-10:]
+	for _, s := range tail {
+		if math.Abs(s) > 0.1 {
+			t.Errorf("tail sample %g not decayed", s)
+		}
+	}
+}
+
+func TestRenderDeterministic(t *testing.T) {
+	p := Defaults()
+	p.Wave = "noise"
+	p.Seed = 42
+	a := Render(&p)
+	b := Render(&p)
+	for i := range a {
+		if a[i] != b[i] {
+			t.Fatalf("noise render not deterministic at sample %d", i)
+		}
+	}
+}
+
+func TestAllWavesAndPresets(t *testing.T) {
+	for _, w := range []string{"square", "saw", "sine", "triangle", "noise"} {
+		p := Defaults()
+		p.Wave = w
+		if s := Render(&p); len(s) == 0 {
+			t.Errorf("wave %s rendered nothing", w)
+		}
+	}
+	for _, name := range []string{"blip", "coin", "explosion", "hurt", "jump", "laser", "powerup"} {
+		p, err := Preset(name, 0)
+		if err != nil {
+			t.Errorf("preset %s: %v", name, err)
+			continue
+		}
+		s := Render(p)
+		var sum float64
+		for _, v := range s {
+			sum += v * v
+		}
+		rms := math.Sqrt(sum / float64(len(s)))
+		if rms < 0.01 {
+			t.Errorf("preset %s is nearly silent (rms %g)", name, rms)
+		}
+		// variants stay valid
+		if _, err := Preset(name, 7); err != nil {
+			t.Errorf("preset %s seed 7: %v", name, err)
+		}
+	}
+	if _, err := Preset("nope", 0); err == nil {
+		t.Error("unknown preset should error")
+	}
+}
+
+func TestWAVRoundTrip(t *testing.T) {
+	p := Defaults()
+	samples := Render(&p)
+	var buf bytes.Buffer
+	if err := WriteWAV(&buf, samples, p.SampleRate); err != nil {
+		t.Fatal(err)
+	}
+	sr, bits, ch, dataBytes, err := ReadWAVHeader(&buf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if sr != 44100 || bits != 16 || ch != 1 {
+		t.Errorf("header: sr=%d bits=%d ch=%d", sr, bits, ch)
+	}
+	if dataBytes != len(samples)*2 {
+		t.Errorf("dataBytes = %d, want %d", dataBytes, len(samples)*2)
+	}
+	if buf.Len() != dataBytes {
+		t.Errorf("body length %d != declared %d", buf.Len(), dataBytes)
+	}
+}
+
+func TestParamsWriteRoundTrip(t *testing.T) {
+	p, err := Preset("coin", 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var buf bytes.Buffer
+	if err := p.Write(&buf, "test"); err != nil {
+		t.Fatal(err)
+	}
+	back, err := Parse(&buf)
+	if err != nil {
+		t.Fatalf("re-parse of written .sfx failed: %v\n%s", err, buf.String())
+	}
+	if back.Freq != p.Freq || back.ArpFactor != p.ArpFactor || back.Seed != p.Seed {
+		t.Errorf("roundtrip mismatch: %+v vs %+v", back, p)
+	}
+}

sfx-maker/sfx/synth.go

@@ -0,0 +1,122 @@
+package sfx
+
+import (
+	"math"
+	"math/rand"
+)
+
+// Render synthesizes the effect into float64 samples in [-1, 1].
+func Render(p *Params) []float64 {
+	sr := float64(p.SampleRate)
+	n := int(p.Duration() * sr)
+	out := make([]float64, n)
+	rng := rand.New(rand.NewSource(p.Seed))
+
+	phase := 0.0
+	noiseVal := 0.0
+	noiseCounter := 0.0
+
+	// one-pole filter states
+	lpState := 0.0
+	hpState := 0.0
+	hpPrevIn := 0.0
+	dt := 1 / sr
+	lpAlpha := 0.0
+	if p.LowPass > 0 {
+		rc := 1 / (2 * math.Pi * p.LowPass)
+		lpAlpha = dt / (rc + dt)
+	}
+	hpAlpha := 0.0
+	if p.HighPass > 0 {
+		rc := 1 / (2 * math.Pi * p.HighPass)
+		hpAlpha = rc / (rc + dt)
+	}
+
+	for i := 0; i < n; i++ {
+		t := float64(i) / sr
+
+		f := p.Freq + p.FreqSlide*t
+		if p.ArpFactor != 0 && p.ArpTime > 0 && t >= p.ArpTime {
+			f *= p.ArpFactor
+		}
+		if p.VibratoDepth > 0 && p.VibratoRate > 0 {
+			f += p.VibratoDepth * math.Sin(2*math.Pi*p.VibratoRate*t)
+		}
+		if f < p.FreqMin {
+			f = p.FreqMin
+		}
+
+		var s float64
+		if p.Wave == "noise" {
+			// pitched noise: new random value f*4 times per second
+			noiseCounter += f * 4 * dt
+			if noiseCounter >= 1 || i == 0 {
+				noiseCounter = math.Mod(noiseCounter, 1)
+				noiseVal = rng.Float64()*2 - 1
+			}
+			s = noiseVal
+		} else {
+			phase += f * dt
+			ph := math.Mod(phase, 1)
+			switch p.Wave {
+			case "square":
+				if ph < p.Duty {
+					s = 1
+				} else {
+					s = -1
+				}
+			case "saw":
+				s = 2*ph - 1
+			case "triangle":
+				if ph < 0.5 {
+					s = 4*ph - 1
+				} else {
+					s = 3 - 4*ph
+				}
+			case "sine":
+				s = math.Sin(2 * math.Pi * ph)
+			}
+		}
+
+		s *= envelope(p, t)
+
+		if lpAlpha > 0 {
+			lpState += lpAlpha * (s - lpState)
+			s = lpState
+		}
+		if hpAlpha > 0 {
+			hpState = hpAlpha * (hpState + s - hpPrevIn)
+			hpPrevIn = s
+			s = hpState
+		}
+
+		s *= p.Volume
+		if s > 1 {
+			s = 1
+		} else if s < -1 {
+			s = -1
+		}
+		out[i] = s
+	}
+	return out
+}
+
+// envelope is a linear attack / sustain / decay gain in 0..1.
+func envelope(p *Params, t float64) float64 {
+	switch {
+	case t < p.Attack:
+		return t / p.Attack
+	case t < p.Attack+p.Sustain:
+		return 1
+	default:
+		d := t - p.Attack - p.Sustain
+		if p.Decay <= 0 {
+			return 0
+		}
+		g := 1 - d/p.Decay
+		if g < 0 {
+			g = 0
+		}
+		return g
+	}
+}

sfx-maker/sfx/wav.go

@@ -0,0 +1,54 @@
+package sfx
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+	"math"
+)
+
+// WriteWAV encodes samples ([-1,1] floats) as a 16-bit mono PCM WAV.
+func WriteWAV(w io.Writer, samples []float64, sampleRate int) error {
+	dataLen := len(samples) * 2
+	var hdr [44]byte
+	copy(hdr[0:4], "RIFF")
+	binary.LittleEndian.PutUint32(hdr[4:8], uint32(36+dataLen))
+	copy(hdr[8:12], "WAVE")
+	copy(hdr[12:16], "fmt ")
+	binary.LittleEndian.PutUint32(hdr[16:20], 16)                   // fmt chunk size
+	binary.LittleEndian.PutUint16(hdr[20:22], 1)                    // PCM
+	binary.LittleEndian.PutUint16(hdr[22:24], 1)                    // mono
+	binary.LittleEndian.PutUint32(hdr[24:28], uint32(sampleRate))   // sample rate
+	binary.LittleEndian.PutUint32(hdr[28:32], uint32(sampleRate*2)) // byte rate
+	binary.LittleEndian.PutUint16(hdr[32:34], 2)                    // block align
+	binary.LittleEndian.PutUint16(hdr[34:36], 16)                   // bits per sample
+	copy(hdr[36:40], "data")
+	binary.LittleEndian.PutUint32(hdr[40:44], uint32(dataLen))
+	if _, err := w.Write(hdr[:]); err != nil {
+		return err
+	}
+	buf := make([]byte, 2*len(samples))
+	for i, s := range samples {
+		v := int16(math.Round(s * 32767))
+		binary.LittleEndian.PutUint16(buf[i*2:], uint16(v))
+	}
+	_, err := w.Write(buf)
+	return err
+}
+
+// ReadWAVHeader sanity-parses a WAV header (used in tests and info).
+func ReadWAVHeader(r io.Reader) (sampleRate, bits, channels, dataBytes int, err error) {
+	var hdr [44]byte
+	if _, err = io.ReadFull(r, hdr[:]); err != nil {
+		return
+	}
+	if string(hdr[0:4]) != "RIFF" || string(hdr[8:12]) != "WAVE" {
+		err = fmt.Errorf("not a WAV file")
+		return
+	}
+	channels = int(binary.LittleEndian.Uint16(hdr[22:24]))
+	sampleRate = int(binary.LittleEndian.Uint32(hdr[24:28]))
+	bits = int(binary.LittleEndian.Uint16(hdr[34:36]))
+	dataBytes = int(binary.LittleEndian.Uint32(hdr[40:44]))
+	return
+}