Update CI and target configuration files

Author: KristofferKarlAxelEkstrand

.github/workflows/ci.yml

@@ -25,11 +25,12 @@ jobs:
           sudo apt-get install -y --no-install-recommends \
             sox libsox-fmt-all libsndfile1 gnuplot ffmpeg
 
-      - name: Install Python dependencies
-        run: pip install -r requirements.txt
+      - name: Install pre-commit
+        run: pip install pre-commit
 
-      - name: Check formatting
-        run: bash scripts/check-format.sh
+
+      - name: Run pre-commit formatting checks
+        run: pre-commit run --all-files
 
       - name: Smoke build (one bank per target)
         run: bash scripts/ci-smoke.sh

AGENT.md

@@ -63,32 +63,38 @@ AKWF-FREE/
 │       ├── AKWF_cello/
 │       └── ...                # ~4358 waveforms across 65 banks
 │
-├── targets/                    # Target definitions (one file per target)
-│   ├── akai-mpc.yml
-│   ├── surge-1024.yml
-│   ├── teensy-c.yml
-│   └── ...
+├── targets/                    # Target definitions
+│   ├── README.md              # Target definition schema & docs
+│   ├── akwf-standard.yml      # Matrix: all power-of-2 × bit depth × SR combos
+│   ├── akai-mpc.yml           # Akai MPC sampler format
+│   ├── surge-1024.yml         # Surge synth 1024-sample wavetables
+│   ├── surge-512.yml          # Surge synth 512-sample wavetables
+│   ├── teensy-c.yml           # Teensy C header arrays
+│   ├── web-json.yml           # JSON for web players
+│   └── png-plots.yml          # PNG waveform visualizations
 │
 ├── scripts/                    # Build/conversion tooling
-│   ├── convert.py             # Main conversion engine (WAV, JSON, C, PNG)
-│   ├── validate.py            # Single-directory WAV validation
+│   ├── convert.py             # Main conversion engine
+│   ├── targets.py             # Shared target-YAML loading/matrix expansion
+│   ├── validate.py            # Output quality validation
 │   ├── validate-built.py      # Validate all dist/ outputs
 │   ├── package.py             # Zip packaging for releases
 │   ├── check-format.sh        # Line-ending and config checks
 │   └── ci-smoke.sh            # CI one-bank-per-target build
 │
+├── Makefile                    # check, smoke, build, validate, package, clean
 ├── requirements.txt            # Pinned Python dependencies
-├── Makefile                    # check, smoke, build, validate, package
 ├── .github/workflows/ci.yml    # GitHub Actions CI
 │
 ├── dist/                       # Built outputs (gitignored, generated)
+│   ├── AKWF--64smp-16bit-44_1k/
+│   ├── AKWF--1024smp-32bit-48k/
 │   ├── AKWF--Akai-MPC/
-│   ├── AKWF--Surge/
 │   └── ...
 │
-├── releases/                   # Zip archives (gitignored, for GitHub releases)
+├── releases/                   # Zip archives (gitignored)
 │
-├── AKWF--*/                    # Legacy pre-built outputs (being migrated to dist/)
+├── AKWF--*/                    # Legacy pre-built outputs (to be migrated to dist/)
 ├── AKWF-c/                     # Legacy C headers (regenerate via targets/teensy-c.yml)
 ├── AKWF-js/                    # Legacy JSON (regenerate via targets/web-json.yml)
 └── AKWF-png/                   # Legacy PNG plots (regenerate via targets/png-plots.yml)
@@ -105,88 +111,120 @@ make check                                              # format checks + list t
 make smoke                                              # one bank per target (CI)
 make build TARGET=targets/akai-mpc.yml BANK=AKWF_0001   # single target
 make build                                              # full library (slow)
-make validate BANK=AKWF_0001
+make validate                                           # validate built outputs
 make package                                            # zip to releases/
+make clean                                              # remove dist/ and releases/
 ```
 
 Or directly:
 
 ```bash
-python3 scripts/convert.py --target targets/akai-mpc.yml
+python3 scripts/convert.py --target targets/akwf-standard.yml --bank AKWF_0001
 python3 scripts/convert.py --all
-python3 scripts/convert.py --target targets/akai-mpc.yml --dry-run
+python3 scripts/convert.py --list
 ```
 
-**Dependencies:** `pip install -r requirements.txt` plus system tools SoX, gnuplot, FFmpeg.
-The dev container installs everything automatically.
+**Dependencies:** `pip install -r requirements.txt`
 
 ### Adding a New Target
 
-1. Create a YAML definition in `targets/` (see existing targets for schema)
-2. The definition specifies: output format, sample length, bit depth, sample rate, normalization, naming conventions, folder structure
-3. Run the conversion script to generate the output in `dist/`
-
-### Target Definition Schema
+**Single target:** Create a YAML file in `targets/`:
 
 ```yaml
 name: "Akai MPC"
 output_dir: "AKWF--Akai-MPC"
 description: "Format compatible with Akai MPC samplers"
 
 audio:
-  format: wav
-  bit_depth: 16
+  format: wav                 # wav | raw | c-header | json | png | custom
+  bit_depth: 16                # 8 | 16 | 24 | 32 (32 = float)
   sample_rate: 44100
-  channels: mono
-  length_samples: 600        # target cycle length
-  
+  channels: mono              # mono | stereo (stereo duplicates the mono signal to both channels)
+  length_samples: 600
+
+resample:
+  method: none               # none | sinc | linear | sox-speed | sox-rate
+  quality: high               # low | medium | high | very-high — only affects sox-rate
+
 normalize:
   enabled: true
-  target_dbfs: 0.0           # peak normalize to 0 dBFS
-  
+  method: peak               # peak | gain
+  target_dbfs: -0.1
+  gain_db: -6.4               # used when method is gain (legacy SoX `gain` parity, e.g. Surge targets)
+  remove_dc: true
+
 naming:
-  extension: ".WAV"          # uppercase for MPC compatibility
-  filename_case: preserve    # preserve original filename case
+  extension: ".WAV"
+  filename_case: preserve    # preserve | upper | lower
+  extension_case: upper      # lower | upper
 
 structure:
-  mirror_source: true        # replicate src/AKWF bank/file structure
+  mirror_source: true
 
 metadata:
-  add_loop_points: true      # WAV smpl chunk: loop 0..length-1
+  add_loop_points: true
+
+packaging:
+  zip: true
+  zip_name: "AKWF--Akai-MPC.zip"
+
+skip:
+  banks: ["AKWF_stereo"]
 ```
 
-### Normalization
+**Matrix target:** Use `type: matrix` for combinations:
 
-- All targets should specify normalization settings
-- Peak normalization to 0 dBFS means the loudest sample hits exactly ±1.0
-- Some targets may want headroom (e.g., -1 dBFS, -3 dBFS)
-- Normalization is per-file (each waveform independently)
+```yaml
+type: matrix
 
-### Resampling (Changing Cycle Length)
+matrix:
+  length_samples: [64, 128, 256, 512, 1024, 2048]
+  bit_depth: [16, 32]
+  sample_rate: [44100, 48000]
 
-When converting 600 samples to a different length (e.g., 1024):
-- Use high-quality sinc interpolation (band-limited)
-- Single-cycle waveforms MUST remain seamlessly loopable
-- The resampled waveform must have the same spectral content
-- Power-of-2 lengths preferred for synthesizer compatibility: 64, 128, 256, 512, 1024, 2048
+defaults:
+  # Same fields as single target — applied to all combinations
+
+output_template:
+  dir: "AKWF--{length}smp-{bits}bit-{rate_k}k"
+  zip: "AKWF--{length}smp-{bits}bit-{rate_k}k.zip"
+  name: "AKWF {length}smp {bits}-bit {rate_k}kHz"
+```
 
-### Tools Available
+### Resampling
 
-- **Makefile** — `check`, `smoke`, `build`, `validate`, `package`, `clean`
-- **SoX** (`sox`) — resampling for C-header targets (`sox-speed` method)
-- **gnuplot** — ASCII art in C headers and PNG waveform plots
-- **FFmpeg** (`ffmpeg`) — format probing, edge cases
-- **Python 3.11+** with `requirements.txt` — numpy, scipy, soundfile, PyYAML, tqdm
+- **FFT-based sinc** (`scipy.signal.resample`) — default, mathematically optimal for periodic signals
+- Treats signal as periodic (exactly what single-cycle waveforms are)
+- Preserves all harmonics below Nyquist with zero aliasing
+- Output is perfectly loopable
+- All processing in 64-bit float internally
+- **sox-rate** (legacy Teensy AKWF-c approach) resamples via SoX's `rate` effect; `resample.quality` maps to SoX's quality presets here (no-op for `sinc`/`linear`/`sox-speed`)
+- **sox-speed** (legacy AKWF--Surge approach) resamples via SoX's `speed` factor for bit-exact legacy parity
 
-### Resampling Math
+### Dithering
 
-To change from 600 samples to N samples using SoX `speed`:
-- `speed_factor = 600 / N`
-- Example: 600 → 1024: `speed 0.5859375` (= 600/1024)
-- Example: 600 → 512: `speed 1.171875` (= 600/512)
-- Example: 600 → 2048: `speed 0.29296875` (= 600/2048)
+- **TPDF** (Triangular Probability Density Function) applied when quantizing to 8-bit, 16-bit, or 24-bit — `wav`/`raw` formats only
+- Decorrelates quantization error, replacing distortion with a tiny noise floor
+- 32-bit float output skips dithering
+- `c-header` output is never dithered — it quantizes straight to `uint16` via `float_to_uint16()`, not through the wav/raw dither path
 
-Note: SoX `speed` changes both length and effective sample rate. The output file keeps 44100 Hz in the header but the cycle is now N samples long.
+### Validation
+
+`scripts/validate.py` dispatches by output format (wav/raw/json/c-header/png), auto-detected from the directory contents or read from `--target`:
+
+```bash
+python3 scripts/validate.py dist/AKWF--1024smp-16bit-44_1k/
+python3 scripts/validate.py dist/AKWF--1024smp-16bit-44_1k/ --target targets/akwf-standard.yml
+```
+
+`scripts/validate-built.py` (what `make validate` runs) does the same across every target in `dist/` at once.
+
+### Packaging
+
+```bash
+python3 scripts/package.py --target targets/akwf-standard.yml
+python3 scripts/package.py --all
+```
 
 ### Release Process
 
@@ -199,16 +237,17 @@ Note: SoX `speed` changes both length and effective sample rate. The output file
 ## Conventions
 
 - Source files in `src/AKWF/` are NEVER modified by build scripts
-- All generated/converted output goes to `dist/` or target-specific folders
+- All generated output goes to `dist/`
 - File names preserve the `AKWF_` prefix
 - Bank folder names preserve the `AKWF_` prefix
 - One waveform = one file = one single cycle
 - The `AKWF_stereo` bank is special (stereo files) — skip or handle per target
+- Output naming: `AKWF--{length}smp-{bits}bit-{rate_k}k` (double-dash prefix)
+- Rate uses underscore: `44_1k` not `44.1k` (dots in filenames cause issues)
 
 ## Important Notes
 
-- The source is 600 samples — this is an unusual, non-power-of-2 length by historical design
-- Some waveforms are already peak-normalized to 0 dBFS, some are not
+- The source is 600 samples — an unusual, non-power-of-2 length by historical design
 - The collection has ~4358 mono waveforms across 65 banks
 - License is CC0 — completely public domain, no attribution required
 - The project currently lives on the `updates` branch; `master` is the default/release branch

AKWF--Surge/README.md

@@ -1,9 +1,9 @@
 # AKWF for Surge
 
-The [free and open source synth Surge](https://surge-synthesizer.github.io/) can load single cycle waveforms directly. The Surge team also provides a python tool (wt-tool.py) for creating Wavetables using single cycle waveforms. You can download those tools or read about how to use them here:  
+The [free and open source synth Surge](https://surge-synthesizer.github.io/) can load single cycle waveforms directly. The Surge team also provides a python tool (wt-tool.py) for creating Wavetables using single cycle waveforms. You can download those tools or read about how to use them here:
 ---> [Surge Wavetable Wiki](https://github.com/surge-synthesizer/surge-synthesizer.github.io/wiki/Creating-Wavetables-for-Surge)<---
 
-Adventure Kid waveforms are traditionally 600 samples long but Surge requires Wavetables to be power-of-2 cycle lengths (.... 64, 128, 256, 512, etc).  
+Adventure Kid waveforms are traditionally 600 samples long but Surge requires Wavetables to be power-of-2 cycle lengths (.... 64, 128, 256, 512, etc).
 This folder contains versions of the AKWF library converted to 64 (kinda silly), 512(reasonable), and 1024(higher quality) samples.
 Also included is a set of Wavetables in WT format made from each folder inside of AKWF-512.
 
@@ -25,23 +25,23 @@ for d in ./*/;
         for file in $(find *.wav);
             do sox "$file" ./"$d"/"$file" speed 0.5859 gain -6.4;
             cp -r "$d" ~/Desktop/AKWF-1024/"$d";
-        done;        
+        done;
 
-#512 version DOWNSCALE      
-#        mkdir ~/Desktop/AKWF-512   
+#512 version DOWNSCALE
+#        mkdir ~/Desktop/AKWF-512
 #        for file in $(find *.wav);
 #            do sox "$file" "$d"/"$file" speed 1.1718 gain -6.4;
 #            cp -r "$d" ~/Desktop/AKWF-512/"$d";
 #        done;
 
 #64 version SUPER DOWNSCALE
-#Kinda silly TBH    
+#Kinda silly TBH
 
 #        mkdir ~/Desktop/AKWF-64
 #       for file in $(find *.wav);
 #            do sox "$file" ./"$d"/"$file" speed 9.4 gain -6.4;
 #            cp -r "$d" ~/Desktop/AKWF-64/"$d";
-#        done;      
+#        done;
 
 
     cd ..;

Makefile

@@ -5,7 +5,7 @@
 #   make smoke              # CI-style: one bank per target YAML
 #   make build              # full library build (slow)
 #   make build BANK=AKWF_0001 TARGET=targets/akai-mpc.yml
-#   make validate             # validate built WAV outputs
+#   make validate             # validate built outputs
 #   make package            # zip dist/ targets to releases/
 #   make clean              # remove dist/ and releases/
 
@@ -21,7 +21,7 @@ help:
 	@echo "  make smoke     - build one bank per target YAML (CI default)"
 	@echo "  make dry-run   - preview build without writing files"
 	@echo "  make build     - build targets (all, or TARGET=..., BANK=...)"
-	@echo "  make validate  - validate built WAV outputs in dist/"
+	@echo "  make validate  - validate built outputs in dist/"
 	@echo "  make package   - create zip archives in releases/"
 	@echo "  make clean     - remove dist/ and releases/"
 	@echo "  make list      - list available target definitions"
@@ -60,3 +60,6 @@ clean:
 
 list:
 	$(PYTHON) scripts/convert.py --list
+
+format:
+	pre-commit run --all-files